Method descriptor 是协议与类型的交点

一个方法需要精确的 service name、method name、cardinality，以及 request/response marshaller：

1
2
3
4
5
6

var echo = new GrpcMethod<>(
    "testing.EchoService",
    "Echo",
    GrpcMethod.Cardinality.UNARY,
    new ProtobufMarshaller<>(StringValue.parser()),
    new ProtobufMarshaller<>(StringValue.parser()));

它生成的 path 必须是：

1

/testing.EchoService/Echo

服务注册表按完整 path 精确匹配。未知 path 返回 UNIMPLEMENTED，重复注册同一路径在构建 service definition 时立即失败。

Server 先验证协议，再订阅业务

ReactorGrpcServer 使用 Reactor Netty h2c：

1
2
3
4
5
6

DisposableServer bound = HttpServer.create()
    .host(host)
    .port(port)
    .protocol(HttpProtocol.H2C)
    .handle(handler::handle)
    .bindNow(Duration.ofSeconds(10));

请求进入后按顺序验证：

• HTTP method 必须是 POST；
• content-type 必须是 application/grpc 或 application/grpc+...；
• te 必须声明 trailers；
• path 必须存在；
• 当前只允许 unary cardinality；
• metadata 与 message size 不能超过限制。

验证通过后才创建 GrpcCallContext 并订阅 request body，避免无效请求进入业务 Handler。

HTTP 200 不代表 RPC 成功

Server 先写 compatible content-type，最终状态由 trailing headers 产生：

1
2
3
4
5
6
7
8
9
10
11

response.status(200)
    .header(HttpHeaderNames.CONTENT_TYPE, "application/grpc+proto");

response.trailerHeaders(trailers -> {
  GrpcException error = terminal.get();
  if (error == null) {
    writeStatus(trailers, GrpcStatus.OK, GrpcMetadata.empty());
  } else {
    writeStatus(trailers, error.status(), error.trailers());
  }
});

应用抛出的 GrpcException 保留明确 status 与 trailing metadata。普通应用异常映射为 UNKNOWN；协议违规映射为 INTERNAL。Fatal JVM error 不应该被包装成普通业务状态。

Client 收到响应后必须读取最终 grpc-status。HTTP 200 却没有 status 是 INTERNAL；非 gRPC HTTP 404 按标准 fallback 映射为 UNIMPLEMENTED，503 则映射为 UNAVAILABLE。

Metadata 必须保序并允许重复

gRPC metadata 不是普通 Map<String, String>。同一个 key 可以重复，顺序需要保留，-bin 后缀表示二进制值并在 wire 上使用无 padding Base64。

GrpcMetadata 因此内部保存 immutable entry list：

1
2
3
4

GrpcMetadata.builder()
    .addAscii("trace-id", "abc")
    .addBinary("span-bin", bytes)
    .build();

用户 metadata 不能覆盖 content-type、te、grpc-status、grpc-timeout 和 HTTP/2 pseudo headers 等保留字段。读取时还要限制编码后总大小，防止 peer 用 headers 消耗无界内存。

Deadline 的 wire value 不能简单截断

grpc-timeout 由最多八位数字和一个单位组成，例如 100m、2S。格式化时必须向上取整，确保 wire deadline 不会比调用者要求更短：

1
2
3
4

BigInteger amount = ceilDivide(nanos, unit.nanos);
if (amount.compareTo(MAX_VALUE) <= 0) {
  return amount + String.valueOf(unit.suffix);
}

在本篇对应的 Stage 2 提交中，client 只会写入 timeout header，并把 Reactor Netty response timeout 设置得略长，用于区分 gRPC deadline 与底层连接等待。仅能解析 header 还不算完整支持；Stage 5 后续补上了 client 与 server 的 Reactor deadline 定时器、handler 取消和 GrpcCallContext 传播。当前实现仍不会替业务代码自动为 nested call 派生更短的 deadline。

Unary cardinality 用 single 强制执行

Client 对 unary request 使用 requests.single()，response 同样要求一个值。空请求、两个请求、空响应和两个响应都不是隐式默认值，而是明确错误。

当前 transport 测试覆盖：

• unary message 与 ASCII metadata 往返；
• declared error 和 trailing metadata；
• unknown method；
• 空/重复 unary 数据；
• 非 gRPC HTTP 响应与缺失 status；
• client cancellation 传播到 server publisher；
• connection failure 映射为 UNAVAILABLE。

Unary vertical slice 的测试继续作为 streaming transport 的回归基线。Server、client 与 bidirectional streaming 已在后续提交完成；TLS、GOAWAY、keepalive、compression、deadline、连接池和 transport diagnostics 也已在 Stage 5 完成并进入 main。

Client 请求的完整生命周期

ReactorGrpcClient 的 unary 调用最终映射为一次完整的 HTTP/2 stream 交互。下面是从用户调用到网络响应的全路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

client.unary(method, Mono.just(request))
    │
    ├─ Flux.defer() → 惰性组装，每次订阅独立
    │
    ├─ channel.select() → 选取 subchannel（Stage 2 固定单连接）
    │
    ├─ httpClient.post(method.path())
    │   ├─ 写 HTTP/2 request headers
    │   │   content-type: application/grpc+proto
    │   │   te: trailers
    │   │   grpc-accept-encoding: gzip
    │   │   grpc-timeout: <if set>
    │   │   custom metadata
    │   │
    │   ├─ onEventLoop() → 在连接的 event loop 上序列化
    │   │
    │   ├─ GrpcOutboundMessageEncoder.encode()
    │   │   ├─ marshaller.serialize() → Protobuf → ByteBuf
    │   │   ├─ 校验 size ≤ maxOutboundMessageSize
    │   │   └─ GrpcFrameCodec.encode() → 5 字节 header + payload
    │   │
    │   └─ outbound.send(requestFrames) → HTTP/2 DATA frame
    │
    └─ .response((response, content) → decodeResponse)
        ├─ 检查 response headers 中的 grpc-status（trailers-only 错误）
        ├─ 校验 HTTP 200 + content-type = application/grpc
        ├─ 读取 grpc-encoding header
        ├─ GrpcFrameCodec.decode(content) → 增量帧解析
        ├─ marshaller.deserialize() → ByteBuf → Response protobuf
        └─ 读取 trailers 中的 grpc-status + grpc-message

关键设计：整个 pipeline 是 lazy 的——在 Mono 被订阅之前不会发起 HTTP/2 连接。这与 grpc-java 的 ClientCall.start() 即触发连接的模式不同。

为什么要在 event loop 上序列化

Reactor Netty 的每条 HTTP/2 连接绑定到一个 Netty event loop 线程。如果 marshalling 发生在用户线程，序列化产生的 ByteBuf 需要跨线程传递给 event loop，带来额外的同步开销。

onEventLoop() 把序列化推迟到连接的 event loop 上执行：

1
2
3
4
5
6

private <T> Flux<T> onEventLoop(NettyOutbound outbound, Flux<T> source) {
    return source.publishOn(
        Schedulers.fromExecutor(outbound.alloc().buffer(0).alloc()
            ... // 获取 event loop executor
        ));
}

这样做的好处：

• 序列化和网络写入在同一线程，无锁；
• ByteBuf 的 allocator 与连接一致，减少跨 arena 分配；
• concatMap(..., 1) 控制 prefetch，保证消息严格按序发出。

错误映射：从 HTTP/2 异常到 gRPC 状态

网络层的错误不能直接暴露给用户，需要映射到 gRPC 语义：

这个映射遵循 gRPC 协议规范中定义的 HTTP status code 到 gRPC status 的转换表。UNAVAILABLE 意味着客户端可以重试；INTERNAL 和 UNIMPLEMENTED 通常不值得重试。

Client 取消如何传播到 Server

Reactor 的 dispose() 需要映射为 HTTP/2 的 RST_STREAM，让 server 知道这条调用已经不需要了：

1
2
3
4
5
6

client: subscription.dispose()
    → Reactor Netty 观察到 subscriber cancel
    → 发送 HTTP/2 RST_STREAM frame
    → Server 连接收到 RST_STREAM
    → request body publisher 被 cancel
    → server handler 的 Mono/Flux 收到 cancel signal

Server 侧通过 connection handler 监听 stream 关闭事件，将其转换为 peerCancellation signal。业务 handler 使用 takeUntilOther(peerCancellation) 订阅这个 signal，确保 client 取消后 server 不再做无用计算。

这一机制让 Reactor 的背压语义（cancel = 我不再需要数据）与 gRPC 的取消语义（RST_STREAM = 调用已中止）自然对齐。

与 grpc-java 的互操作验证

Stage 2 的退出条件不是”自己调自己成功”，而是必须与 grpc-java 双向互通。UnaryInteroperabilityTest 验证两个方向：

Reactor client → grpc-java server：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

@Test
void reactorClientCallsGrpcJavaServer() {
    try (var fixture = GrpcJavaFixture.start();
         var client = ReactorGrpcClient.builder().port(fixture.port()).build()) {
        var response = stub.unary(Mono.just(request("hello"))).block();
        assertEquals("hello", response.getValue());

        // 验证错误 status 和 trailing metadata 正确传递
        var error = assertThrows(GrpcException.class,
            () -> stub.unary(Mono.just(request("error"))).block());
        assertEquals(GrpcStatus.Code.INVALID_ARGUMENT, error.status().code());
        assertEquals("rejected", error.status().message());
        assertEquals("fixture", error.trailers().getLast("error-id").orElseThrow().asciiValue());
    }
}

grpc-java client → Reactor server：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

@Test
void grpcJavaClientCallsReactorServer() {
    var service = InteropTestServiceReactorGrpc.bindService(new Service() {
        @Override
        public Mono<TestResponse> unary(GrpcCallContext context, Mono<TestRequest> requests) {
            return requests.map(req -> {
                if (req.getValue().equals("error")) {
                    throw new GrpcException(
                        new GrpcStatus(GrpcStatus.Code.INVALID_ARGUMENT, "rejected"),
                        GrpcMetadata.builder().addAscii("error-id", "reactor").build());
                }
                return TestResponse.newBuilder().setValue(req.getValue()).build();
            });
        }
    });

    try (var server = ReactorGrpcServer.builder().addService(service).start()) {
        var stub = InteropTestServiceGrpc.newBlockingStub(channel);
        assertEquals("hello", stub.unary(request("hello")).getValue());

        var error = assertThrows(StatusRuntimeException.class,
            () -> stub.unary(request("error")));
        assertEquals(Status.Code.INVALID_ARGUMENT, error.getStatus().getCode());
    }
}

两个方向都验证了：正常响应、错误 status code、错误 message 的 percent-encoding 往返，以及自定义 trailing metadata 的传递。只有 grpc-java 能正确解析 Reactor server 的响应，才能证明 wire protocol 实现是兼容的。

Stage 2 退出条件

• ./gradlew clean spotlessCheck test --no-daemon 全量通过
• Reactor client ↔ grpc-java server 双向 unary 调用成功
• grpc-java client ↔ Reactor server 双向 unary 调用成功
• 错误 status、message、trailing metadata 正确传递
• Client cancellation 通过 RST_STREAM 传播到 server
• 连接失败映射为 UNAVAILABLE
• 未知路径映射为 UNIMPLEMENTED
• Stage 0 和 Stage 1 的全部测试继续绿灯

下一篇进入 Stage 3 和 Stage 4：在同一 transport primitive 上实现 server streaming、client streaming 和 bidirectional streaming，面对的新挑战是多消息流的背压协调、有界入站缓冲和流提前终止的资源回收。

gRPC protobuf messages are not written directly as raw bytes into HTTP/2 DATA frames. Every message starts with a five-byte envelope:

1
2
3

byte 0      bit 0 indicates compression; bits 1-7 must be zero
bytes 1-4   unsigned big-endian payload length
byte 5..n   protobuf message, or its compressed representation

Encoding this envelope is straightforward. The difficult part is decoding it without assuming that one input buffer contains one complete frame. HTTP/2, TCP, and Reactor Netty do not promise that buffer boundaries will line up with gRPC message boundaries.

This post describes the Stage 1 protocol layer. The project has since progressed beyond it, but the ownership and bounded-decoding rules introduced here remain the foundation for the later transport stages.

Encoding Must Define Ownership

The contract of GrpcFrameCodec.encode is deliberately explicit: the returned frame and the input message have independent lifetimes. Encoding must not move the input reader index or release the input buffer.

The implementation currently copies the readable bytes into a byte array before applying compression:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public static ByteBuf encode(
        ByteBufAllocator allocator,
        ByteBuf message,
        GrpcCompression.Codec compression) {
    boolean compressed = !compression.name().equals("identity");
    byte[] payload = new byte[message.readableBytes()];
    message.getBytes(message.readerIndex(), payload);
    if (compressed) {
        payload = compression.compress(payload);
    }
    return allocator.buffer(GrpcFrameCodec.HEADER_SIZE + payload.length)
            .writeByte(compressed ? 1 : 0)
            .writeInt(payload.length)
            .writeBytes(payload);
}

This is not a zero-copy implementation, and it should not be presented as the fastest possible design. The copy makes the ownership boundary easy to reason about first. If a later optimization uses a slice or a composite buffer, cancellation and exception paths must be re-proven instead of assuming that the old ownership rules still hold.

The Decoder Is a Per-Subscription State Machine

decode uses Flux.defer so every subscription receives an independent decoder instance:

1
2
3
4
5
6
7
8
9
10

return Flux.defer(() -> {
    var decoder = new Decoder(
            maxWireMessageSize,
            maxDecompressedMessageSize,
            compression,
            maxBufferedBytesPerStream);
    return input.concatMap(decoder::accept, 1)
            .concatWith(Flux.defer(decoder::finish))
            .publishOn(Schedulers.immediate(), 1);
});

The state is intentionally small: either the five-byte header is incomplete, or the header is complete and the decoder is collecting a payload of a known length. One input ByteBuf may contain one byte of a header, or three complete messages back-to-back.

concatMap(..., 1) preserves source order and limits the number of source buffers being processed at once. The decoder still has to respect downstream demand when it emits decoded messages. Every source buffer is released in doFinally, including success, failure, and cancellation:

1
2
3
4
5
6
7
8
9
10
11
12
13

private Flux<ByteBuf> accept(ByteBuf source) {
    return Flux.<ByteBuf>generate(sink -> {
        try {
            while (source.isReadable()) {
                // read the header, allocate a bounded payload,
                // and emit a complete message when available
            }
            sink.complete();
        } catch (Throwable error) {
            sink.error(error);
        }
    }).doFinally(ignored -> source.release());
}

The complete implementation also tracks an explicit per-stream buffered-byte limit. That limit covers an incomplete header, a partial payload, and bytes still present in the current source buffer.

Validate Peer Input Before Allocating

The length field comes from the peer, so it must be validated before allocating a payload array. The decoder first combines the unsigned big-endian bytes in a long, then checks the wire-size limit:

1
2
3
4
5
6
7
8

long length = ((long) (header[1] & 0xff) << 24)
        | ((long) (header[2] & 0xff) << 16)
        | ((long) (header[3] & 0xff) << 8)
        | (header[4] & 0xffL);

if (length > maxWireMessageSize) {
    throw new GrpcProtocolException("wire message length exceeds limit");
}

Wire size and decompressed size are separate limits. A tiny gzip payload can expand into a huge message, so gzip decompression must enforce a second output limit to defend against decompression bombs.

Only the lowest compression-flag bit is valid. Any reserved bit is a protocol error. A compressed frame received while the negotiated codec is still identity is also rejected; the decoder must not guess which algorithm the peer intended.

Test Every Header Split Point

Testing one arbitrary two-buffer split is not enough. A five-byte header has six representative split positions, including before the first byte and after the complete header. The test suite uses a dynamic test for every split from 0 through 5:

1
2
3
4
5
6
7
8
9
10
11
12

IntStream.rangeClosed(0, GrpcFrameCodec.HEADER_SIZE)
        .mapToObj(split -> DynamicTest.dynamicTest(
                "split after byte " + split,
                () -> {
                    byte[] wire = wireBytes("hello");
                    Flux<ByteBuf> chunks = Flux.just(
                            wrapped(wire, 0, split),
                            wrapped(wire, split, wire.length - split));
                    StepVerifier.create(GrpcFrameCodec.decode(chunks))
                            .assertNext(message -> assertMessage(message, "hello"))
                            .verifyComplete();
                }));

The same test class covers arbitrary body fragmentation, multiple messages coalesced into one buffer, empty messages, gzip, reserved flags, truncated frames, wire/decompressed limits, and the fact that encoding does not consume the input buffer. See GrpcFrameCodecTest for the executable cases.

Cancellation Must Release Undelivered Data

Suppose one source ByteBuf contains three messages: one, two, and three. The downstream requests two messages and then cancels. The test must assert not only the values it received, but also that the source buffer was released:

1
2
3
4
5
6
7
8
9

StepVerifier.create(GrpcFrameCodec.decode(Flux.just(source)), 0)
        .thenRequest(1)
        .assertNext(message -> assertMessage(message, "one"))
        .thenRequest(1)
        .assertNext(message -> assertMessage(message, "two"))
        .thenCancel()
        .verify();

assertEquals(0, source.refCnt());

That assertion is more important than a happy-path content check. Network code often behaves correctly under normal completion; leaks tend to appear during cancellation, size-limit failures, truncated frames, or competing terminal signals.

Cancellation can also arrive before a complete message exists. In that case there is no decoded value for the subscriber to release, so the decoder itself must release the partially accumulated source buffer:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

@Test
void releasesPartialFrameInputWhenCancelled() {
    ByteBuf partial = Unpooled.buffer(8)
            .writeByte(0)
            .writeInt(16)
            .writeBytes(new byte[]{1, 2, 3});

    StepVerifier.create(
                    GrpcFrameCodec.decode(
                            Flux.just(partial).concatWith(Flux.never())),
                    0)
            .thenRequest(1)
            .thenAwait(java.time.Duration.ofMillis(10))
            .thenCancel()
            .verify();

    assertEquals(0, partial.refCnt());
}

The full executable case is releasesPartialFrameInputWhenCancelled. It covers the lifecycle edge that a normal decode-complete test cannot exercise.

Run only the frame codec suite from the repository root:

1
2
3

./gradlew :grpc-reactor-protocol:test \
  --tests io.github.qianwj.grpc.reactor.protocol.GrpcFrameCodecTest \
  --no-daemon

On JDK 25, the Gradle build and generated JUnit report produced:

1
2

GrpcFrameCodecTest: 15 tests, 0 failures, 0 errors, 0 skipped
BUILD SUCCESSFUL in 3s

At the Stage 1 boundary, the frame decoder verifies message-level demand but does not yet implement the two-level flow-control problem of the streaming transport. Reactive Streams counts messages, while HTTP/2 flow control counts bytes. They cannot be treated as the same quantity. Stage 3 later adds bounded inbound buffering and demand-aware delivery, and Stage 4 extends those rules to bidirectional streaming. Those transport and stress tests are covered in later posts.

Metadata: Ordering, Duplicates, and Binary Values

gRPC metadata is not a simple Map<String, String>. It must satisfy all of these rules:

• The same key may occur more than once, and insertion order matters.
• Keys may contain only lowercase letters, digits, _, ., and -, validated by [0-9a-z_.-]+.
• Keys ending in -bin carry binary values and use unpadded Base64 on the wire.
• Applications cannot set reserved fields such as content-type, te, grpc-status, or grpc-timeout.

GrpcMetadata stores an immutable entry list so it can be safely shared across asynchronous boundaries:

1
2
3
4
5
6
7
8

GrpcMetadata metadata = GrpcMetadata.builder()
        .addAscii("trace-id", "abc123")
        .addAscii("trace-id", "def456") // duplicates are allowed
        .addBinary("auth-token-bin", tokenBytes)
        .build();

// Order is preserved when reading.
List<GrpcMetadata.Entry> all = metadata.getAll("trace-id"); // [abc123, def456]

When parsing HTTP/2 headers, a binary value may be comma-joined by header handling. The implementation splits it on commas and decodes each Base64 segment independently. The total encoded size is bounded at 8 KiB by default, preventing a peer from exhausting memory with oversized headers.

Status: 17 Codes and Percent-Encoding

gRPC defines 17 standard status codes, each with a specific meaning for client error handling and future retry policies. GrpcStatus is a record containing a code and a human-readable message:

1
2
3
4
5
6
7
8
9
10

public record GrpcStatus(Code code, String message) {
    public enum Code {
        OK(0), CANCELLED(1), UNKNOWN(2), INVALID_ARGUMENT(3),
        DEADLINE_EXCEEDED(4), NOT_FOUND(5), ALREADY_EXISTS(6),
        PERMISSION_DENIED(7), RESOURCE_EXHAUSTED(8),
        FAILED_PRECONDITION(9), ABORTED(10), OUT_OF_RANGE(11),
        UNIMPLEMENTED(12), INTERNAL(13), UNAVAILABLE(14),
        DATA_LOSS(15), UNAUTHENTICATED(16);
    }
}

Several details matter in practice:

• DEADLINE_EXCEEDED may be returned even after the operation completed successfully. If the successful response crosses the deadline in transit, the client can still observe a timeout.
• UNAVAILABLE indicates a transient failure for which a client may later retry safely; INTERNAL generally describes a server-side bug and should not be blindly retried.
• UNIMPLEMENTED carries the semantic meaning of an unsupported method, commonly surfaced through an HTTP 404 response at the protocol boundary.

Text in the grpc-message trailer uses percent-encoding: printable ASCII characters other than % can pass through, while other bytes become %HH. This allows UTF-8 error descriptions to travel through ASCII HTTP/2 headers safely.

Unknown numeric status codes are mapped to UNKNOWN instead of causing a parse failure. That preserves forward compatibility when a peer adopts a newer gRPC specification.

Timeout: Eight Digits and a Unit

The gRPC grpc-timeout header carries a relative duration, not an absolute timestamp. By the time the server receives a request, part of the caller’s original time budget has already been consumed by transport latency.

The wire format is compact: at most eight decimal digits followed by a unit suffix:

1
2
3

100m       -> 100 milliseconds
2S         -> 2 seconds
99999999H  -> roughly 11,415 years (the maximum value)

The six units are H (hours), M (minutes), S (seconds), m (milliseconds), u (microseconds), and n (nanoseconds).

When formatting a Duration, the implementation rounds upward using ceiling division. The encoded deadline must never be shorter than the caller’s requested duration:

1
2

BigInteger amount = nanos.add(unitNanos.subtract(BigInteger.ONE))
        .divide(unitNanos); // ceiling division

BigInteger avoids overflow during nanosecond arithmetic. The formatter scans from nanoseconds upward and selects the first unit whose value fits within 99,999,999.

Compression: Identity by Default, Gzip Built In

GrpcCompression manages codec registration and negotiation:

1
2
3
4
5
6

GrpcCompression.Registry registry = GrpcCompression.Registry.builder()
        .add(GrpcCompression.GZIP)
        .build();

// Produces grpc-accept-encoding: gzip
String advertised = registry.advertisedEncodings();

identity is always implicit and appears first in the registry. The codec interface has only three operations: a name, byte-array compression, and bounded byte-array decompression.

Gzip decompression reads in 8 KiB chunks and uses Math.addExact() while accumulating the output size. It can stop immediately after exceeding maxDecompressedSize, and arithmetic overflow cannot silently wrap the counter. A 100-byte gzip payload can expand to gigabytes, so decompression-bomb protection is part of the protocol contract rather than an optional optimization.

GrpcMethod: One Description for Four Cardinalities

Each RPC is described by one GrpcMethod record:

1
2
3
4
5
6
7
8
9

var method = new GrpcMethod<>(
        "testing.InteropTestService", // full service name
        "Unary",                      // method name
        GrpcMethod.Cardinality.UNARY,
        new ProtobufMarshaller<>(TestRequest.parser()),
        new ProtobufMarshaller<>(TestResponse.parser()));

method.path();           // /testing.InteropTestService/Unary
method.fullMethodName(); // testing.InteropTestService/Unary

The Cardinality enum exposes singleRequest() and singleResponse(). The transport uses those flags to insert single() at the API boundary, turning cardinality violations into explicit errors instead of silently dropping values.

ProtobufMarshaller: Serialization Does Not Own the Input

ProtobufMarshaller wraps a protobuf Parser<T>:

1
2
3
4
5
6
7
8
9

public ByteBuf serialize(ByteBufAllocator allocator, T value) {
    var result = allocator.buffer(value.getSerializedSize());
    return result.writeBytes(value.toByteArray());
}

public T deserialize(ByteBuf message) {
    ByteBuffer bytes = message.nioBuffer(message.readerIndex(), message.readableBytes());
    return parser.parseFrom(bytes);
}

The important contract is that deserialize reads through a NIO ByteBuffer view. It does not move the input reader index and does not release the input. Ownership remains with the caller, allowing the frame decoder’s doFinally(release) to manage the buffer lifecycle uniformly whether parsing succeeds or fails.

Stage 1 Exit Criteria

The protocol module does not need Reactor Netty on its classpath. That dependency boundary is itself part of the verification. The Stage 1 exit criteria are:

• every header and payload split point decodes correctly;
• cancellation leaves no unreleased ByteBuf (refCnt assertions);
• metadata preserves order, supports binary values, and enforces its size limit;
• unknown status codes do not throw;
• all timeout units parse correctly, formatting rounds upward, and arithmetic is overflow-safe;
• gzip decompression limits reject bombs;
• the marshaller does not change the input buffer state.

These tests use JUnit 5 @TestFactory and DynamicTest for parameterization, together with Reactor Test’s StepVerifier for asynchronous behavior. The protocol layer is the reason the later transport stages can focus on HTTP/2 lifecycle instead of rediscovering framing and ownership rules.

The complete implementation is in GrpcFrameCodec.java. The related protocol primitives are GrpcMetadata, GrpcStatus, GrpcTimeout, GrpcCompression, and ProtobufMarshaller.

1
2
3

byte 0      bit 0 表示是否压缩，bit 1-7 必须为 0
byte 1-4    payload 长度，无符号大端序
byte 5..n   Protobuf 或压缩后的消息体

编码并不复杂，真正困难的是解码不能假设一次收到完整 frame。HTTP/2、TCP 和 Reactor Netty 都不保证 buffer 边界与 gRPC 消息边界一致。

编码必须定义所有权

GrpcFrameCodec.encode 的契约是：返回 frame 与输入 message 各自拥有独立生命周期，编码过程不移动输入的 reader index，也不释放输入。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

public static ByteBuf encode(
    ByteBufAllocator allocator,
    ByteBuf message,
    GrpcCompression.Codec compression) {
  byte[] payload = new byte[message.readableBytes()];
  message.getBytes(message.readerIndex(), payload);
  if (!compression.name().equals("identity")) {
    payload = compression.compress(payload);
  }
  return allocator.buffer(5 + payload.length)
      .writeByte(compressed ? 1 : 0)
      .writeInt(payload.length)
      .writeBytes(payload);
}

当前实现为了先把 ownership 做清楚，会复制为 byte array。它不是零拷贝实现，也不应该被描述成性能最优；后续若改用 slice 或 composite buffer，必须重新证明取消和异常路径没有泄漏。

解码器是每次订阅独立的状态机

decode 使用 Flux.defer 为每个订阅创建 Decoder：

1
2
3
4
5
6
7
8

return Flux.defer(() -> {
  var decoder = new Decoder(
      maxWireMessageSize,
      maxDecompressedMessageSize,
      compression);
  return input.concatMap(decoder::accept, 1)
      .concatWith(Flux.defer(decoder::finish));
});

状态只有两部分：尚未收满的五字节 header，以及已知长度但尚未收满的 payload。一个输入 ByteBuf 可能只包含 header 的一个字节，也可能连续包含三条完整消息。

concatMap(..., 1) 保持输入次序，同时让 decoder 按下游 demand 交付消息。每个 source buffer 最终通过 doFinally 释放：

1
2
3
4
5
6
7
8
9
10
11
12

private Flux<ByteBuf> accept(ByteBuf source) {
  return Flux.<ByteBuf>generate(sink -> {
    try {
      while (source.isReadable()) {
        // read header, allocate bounded payload, emit complete message
      }
      sink.complete();
    } catch (Throwable error) {
      sink.error(error);
    }
  }).doFinally(ignored -> source.release());
}

在分配前验证 peer 输入

长度字段来自远端，不能读取后立即分配。实现先用 long 组合无符号大端整数，再检查 wire size：

1
2
3
4
5
6
7
8

long length = ((long) (header[1] & 0xff) << 24)
    | ((long) (header[2] & 0xff) << 16)
    | ((long) (header[3] & 0xff) << 8)
    | (header[4] & 0xffL);

if (length > maxWireMessageSize) {
  throw new GrpcProtocolException("wire message length exceeds limit");
}

wire size 与 decompressed size 是两个不同限制。一个很小的 gzip payload 可能解压为巨大数据，因此 gzip 解压过程中还必须再次限制输出，防止 decompression bomb。

压缩标志只有最低位合法；保留位不为零直接视为协议错误。收到 compressed frame 但协商结果仍是 identity，同样不能猜测算法继续解码。

测试所有 header 分割点

固定测“拆成两个 buffer”还不够，五字节 header 有六个代表性分割位置。测试使用动态用例覆盖 0 到 5：

1
2
3
4
5
6
7
8
9
10
11
12

IntStream.rangeClosed(0, GrpcFrameCodec.HEADER_SIZE)
    .mapToObj(split -> DynamicTest.dynamicTest(
        "split after byte " + split,
        () -> {
          byte[] wire = wireBytes("hello");
          Flux<ByteBuf> chunks = Flux.just(
              wrapped(wire, 0, split),
              wrapped(wire, split, wire.length - split));
          StepVerifier.create(GrpcFrameCodec.decode(chunks))
              .assertNext(message -> assertMessage(message, "hello"))
              .verifyComplete();
        }));

另外还覆盖：body 任意分片、多 frame 合并、空消息、gzip、保留位、截断 frame、wire/decompressed limit，以及编码不消费输入 buffer。

取消时也要释放未消费数据

一个 source ByteBuf 中合并了 one、two、three 三条消息。下游只请求两条后取消，测试最后断言 source 的引用计数归零：

1
2
3
4
5
6
7

StepVerifier.create(GrpcFrameCodec.decode(Flux.just(source)), 0)
    .thenRequest(1).assertNext(message -> assertMessage(message, "one"))
    .thenRequest(1).assertNext(message -> assertMessage(message, "two"))
    .thenCancel()
    .verify();

assertEquals(0, source.refCnt());

这条断言比“结果内容正确”更重要。网络库中的 happy path 很容易正确，泄漏往往发生在取消、超限、截断或重复 terminal signal 中。

在本篇对应的 Stage 1 提交中，frame decoder 只覆盖了消息级 demand，尚未完成 streaming transport 的两级 flow control。Reactive Streams 计算消息数量，HTTP/2 window 计算字节，两者不能混为一谈。这个边界后来由 Stage 3 的有界入站缓冲与按需交付补齐，并在 Stage 4 扩展到双向流；对应实现和压力测试会在系列第五、六篇展开。

Metadata：保序、重复、二进制三合一

gRPC metadata 不是简单的 Map<String, String>。它必须满足：

• 同一个 key 可以出现多次，顺序敏感；
• key 只允许小写字母、数字、_、. 和 -，由正则 [0-9a-z_.-]+ 校验；
• 以 -bin 结尾的 key 表示二进制值，wire 上使用无 padding Base64 编码；
• 用户不能设置保留字段（content-type、te、grpc-status、grpc-timeout 等）。

GrpcMetadata 内部是一个不可变的 entry list，保证跨异步边界安全共享：

1
2
3
4
5
6
7
8

GrpcMetadata metadata = GrpcMetadata.builder()
    .addAscii("trace-id", "abc123")
    .addAscii("trace-id", "def456")   // 允许重复
    .addBinary("auth-token-bin", tokenBytes)
    .build();

// 读取时保留顺序
List<GrpcMetadata.Entry> all = metadata.getAll("trace-id");  // [abc123, def456]

从 HTTP/2 headers 解析时，二进制值可能被逗号拼接（HTTP/2 合并同名 header 的行为），实现会按逗号拆分后逐段 Base64 解码。编码后总大小有上限（默认 8KB），防止 peer 用超大 headers 耗尽内存。

Status：17 种状态码与 percent-encoding

gRPC 定义了 17 种标准状态码，每种对应一个明确的语义，用于指导客户端的重试和错误处理策略。GrpcStatus 是一个 record，包含 status code 和人类可读 message：

1
2
3
4
5
6
7
8
9
10

public record GrpcStatus(Code code, String message) {
    public enum Code {
        OK(0), CANCELLED(1), UNKNOWN(2), INVALID_ARGUMENT(3),
        DEADLINE_EXCEEDED(4), NOT_FOUND(5), ALREADY_EXISTS(6),
        PERMISSION_DENIED(7), RESOURCE_EXHAUSTED(8),
        FAILED_PRECONDITION(9), ABORTED(10), OUT_OF_RANGE(11),
        UNIMPLEMENTED(12), INTERNAL(13), UNAVAILABLE(14),
        DATA_LOSS(15), UNAUTHENTICATED(16);
    }
}

几个值得注意的设计细节：

• DEADLINE_EXCEEDED 即使操作已成功完成也可能返回——当 server 的成功响应在网络传输中超过了 deadline，client 仍然看到超时；
• UNAVAILABLE 表示暂时性故障，client 可以安全重试；而 INTERNAL 表示 server 内部错误，盲目重试通常无意义；
• UNIMPLEMENTED 对应 HTTP 404 的语义——路径存在但方法不被支持。

grpc-message trailer 中的文本需要 percent-encoding：可打印 ASCII 中除 % 外直接传输，其余字符转为 %HH。这使得 UTF-8 错误描述能安全地通过纯 ASCII 的 HTTP/2 header 传输。

未知的 status code 数值不会抛异常，而是映射到 UNKNOWN——这保证了向前兼容，当 peer 使用了更新的 gRPC spec 定义的新状态码时不会导致解析失败。

Timeout：八位数字 + 单位，向上取整

gRPC 协议规定 grpc-timeout 传输的是相对超时而非绝对时间戳。Server 收到请求时，deadline 已经比 client 设定的少了一次网络传输延迟，必须用剩余时间窗口判断是否应该继续处理。

wire 格式非常紧凑：最多八位十进制数字加一个单位后缀：

1
2
3

100m   → 100 毫秒
2S     → 2 秒
99999999H → 约 11415 年（上限值）

支持六种单位：H（小时）、M（分钟）、S（秒）、m（毫秒）、u（微秒）、n（纳秒）。

格式化 Duration 为 wire value 时，必须向上取整（ceiling division），确保 wire deadline 不会比调用者设定的更短：

1
2

BigInteger amount = nanos.add(unitNanos.subtract(BigInteger.ONE))
    .divide(unitNanos);  // ceiling division

使用 BigInteger 而非 long 避免了 nanosecond 乘法溢出。选择单位的策略是从纳秒向上扫描，取第一个使数值不超过 99,999,999 的单位。

Compression：identity 是默认，gzip 是唯一内置

GrpcCompression 管理 codec 注册和协商：

1
2
3
4
5
6

GrpcCompression.Registry registry = GrpcCompression.Registry.builder()
    .add(GrpcCompression.GZIP)
    .build();

// 产生 grpc-accept-encoding: gzip
String advertised = registry.advertisedEncodings();

identity 始终隐含存在且排在第一位。Codec 接口只有两个方法：

1
2
3
4
5

interface Codec {
    String name();
    byte[] compress(byte[] input);
    byte[] decompress(byte[] input, int maxSize);
}

Gzip 解压使用 8KB chunk 流式读取，每个 chunk 后用 Math.addExact() 累加已解压字节数——这既能在超出 maxSize 时立即中断，也能通过算术溢出检查防止 int wrap-around。一个 100 字节的 gzip payload 可能解压出数 GB 数据，所以 decompression bomb 防护不是可选项。

GrpcMethod：四种 cardinality 的统一描述

每个 RPC 方法用一个 GrpcMethod record 完整描述：

1
2
3
4
5
6
7
8
9

var method = new GrpcMethod<>(
    "testing.InteropTestService",    // fullServiceName
    "Unary",                         // methodName
    GrpcMethod.Cardinality.UNARY,    // cardinality
    new ProtobufMarshaller<>(TestRequest.parser()),
    new ProtobufMarshaller<>(TestResponse.parser()));

method.path();           // "/testing.InteropTestService/Unary"
method.fullMethodName(); // "testing.InteropTestService/Unary"

Cardinality 枚举提供 singleRequest() 和 singleResponse() 查询，transport 层用它在边界插入 single() 操作符，把多值违规转为明确异常而非默默丢弃。

ProtobufMarshaller：序列化不拥有输入

ProtobufMarshaller 包装 Protobuf 的 Parser<T>：

1
2
3
4
5
6
7
8

public ByteBuf serialize(ByteBufAllocator allocator, T value) {
    byte[] bytes = value.toByteArray();
    return allocator.buffer(bytes.length).writeBytes(bytes);
}

public T deserialize(ByteBuf message) {
    return parser.parseFrom(message.nioBuffer());
}

关键契约：deserialize 使用 NIO ByteBuffer 视图读取，不移动 ByteBuf 的 reader index，也不释放输入。所有权始终留给调用者。这个设计让 frame decoder 的 doFinally(release) 可以统一管理所有 buffer 生命周期，不论反序列化成功还是失败。

Stage 1 退出条件

协议模块的测试不需要 Reactor Netty 在 classpath 上——这验证了模块边界的正确性。退出条件：

• 所有 header 分割点 + payload 分割的 frame 解码通过
• 取消路径无 ByteBuf 泄漏（refCnt 断言）
• Metadata 保序、二进制编解码、大小限制生效
• Status 未知 code 不抛异常
• Timeout 所有单位解析、格式化向上取整、溢出安全
• Gzip 解压限制生效（decompression bomb 被拒绝）
• Marshaller 不改变输入 buffer 状态

这些测试使用 JUnit 5 的 @TestFactory + DynamicTest 参数化，配合 Reactor Test 的 StepVerifier 验证异步流行为。协议层完成后，下一篇进入 Stage 2：在 Reactor Netty HTTP/2 上跑通第一条 unary 调用。

This is not about proving grpc-java is bad. grpc-java is mature, stable, and covers load balancing, NameResolver, retries, and rich observability. This project answers a different question: if your programming model is already Reactor, can Mono and Flux flow all the way from the generated API down to the HTTP/2 stream, without adapting between two async abstractions?

This post is based on JDK 25, Gradle 9.2.1, Reactor 3.8.6, Reactor Netty 1.3.6, and Netty 4.2.15.Final. The main branch has completed Stage 0 through Stage 10: beyond protocol, four RPC cardinalities, production transport, DNS, codegen, standard services, and Stage 9 hardening, Stage 10 adds an optional load-balancing extensions artifact for grpclb, RLS, load reporting, and ORCA.

The API Goal Is Not Wrapping StreamObserver

Protobuf methods have four cardinalities. The target API maps them directly:

Why does gRPC define four instead of just unary? It’s essentially a 2x2 combination where request and response each independently choose “single value or stream”:

They solve different scenarios: unary covers classic request-response; server streaming handles server push (event subscriptions, large paginated pulls); client streaming handles bulk uploads (file chunks, batch writes); bidirectional streaming handles real-time two-way communication (chat, collaborative editing). These aren’t invented patterns — HTTP/2 streams are inherently full-duplex. A single connection can multiplex hundreds of concurrent streams, with both request and response sending multiple data frames independently. gRPC elevates this transport capability to first-class API semantics: not a variant of chunked transfer encoding, but compiler-level type checking that callers and implementers match.

The low-level transport retains a single unified model:

1

Flux<Req> -> HTTP/2 stream -> Flux<Resp>

Generated code applies cardinality checks like single() at the boundary. This avoids implementing four separate network logic paths for four RPC types, while explicitly rejecting empty requests, duplicate requests, or duplicate responses in unary calls.

Compatibility Targets the Wire Protocol

The project’s compatibility target is the public gRPC over HTTP/2 protocol spec, not grpc-java internal APIs:

1
2
3
4
5
6
7
8
9

generated Reactor API
        |
call dispatcher / service registry
        |
marshaller + message framer/deframer
        |
metadata + status + deadline
        |
Reactor Netty HTTP/2 stream

Each RPC corresponds to one HTTP/2 stream. Requests start with a HEADERS frame containing at minimum:

1
2
3
4
5

:method      POST
:path        /<package.Service>/<Method>
content-type application/grpc+proto
te           trailers
grpc-timeout <relative timeout, e.g. 100m for 100ms>

Message bodies use Length-Prefixed-Message format encapsulated in DATA frames — each Protobuf message is preceded by a five-byte envelope (1 byte compression flag + 4 bytes big-endian length). A single DATA frame may contain multiple gRPC messages, and a large message may span multiple DATA frames.

Why does gRPC require HTTP trailers? This is one of the protocol’s most counterintuitive designs. HTTP status codes are nearly useless for gRPC — the protocol requires the HTTP layer to always return 200, with the actual call result (grpc-status and grpc-message) placed in trailers. The reason: in streaming scenarios, the server may have already sent thousands of messages, and whether it ultimately succeeded or failed can only be determined after processing the last piece of data. HTTP headers are sent before the body and cannot carry this posterior result. Trailers are the only mechanism in HTTP/2 that can append metadata after the body.

The protocol also defines trailers-only mode: when the server can determine failure before reading the body (e.g., path not found, authentication failed), grpc-status is returned directly in response headers without sending a body, saving one round-trip. Clients must check both headers and trailers to correctly extract the final status.

Modules Split Along Protocol Boundaries

The project currently has nine modules:

1
2
3
4
5
6
7
8
9

grpc-reactor-protocol      → Transport-independent protocol primitives
grpc-reactor-transport     → Reactor Netty HTTP/2 mapping
grpc-reactor-codegen       → Protoc plugin, generates Reactor stubs
grpc-reactor-gradle-plugin → Gradle integration
grpc-reactor-maven-plugin  → Maven generate-sources integration
grpc-reactor-services      → Optional Health, Reflection & Channelz standard services
grpc-reactor-binlog        → Optional, bounded canonical binary logging
grpc-reactor-lb-extensions → Optional grpclb, RLS, load reporting & ORCA
grpc-reactor-interop-test  → grpc-java compatibility tests

protocol handles only transport-independent values and codecs: message framing, metadata, status, timeout, compression, and protobuf marshallers. It depends on Reactor Core and Netty Buffer but not Reactor Netty — meaning the protocol layer can be tested independently without real HTTP/2 connections.

transport maps the protocol onto Reactor Netty HTTP/2, handling client, server, service registry, and per-call context.

codegen consumes Protobuf CodeGeneratorRequest and generates type-safe Reactor client and service binders.

services uses the same codegen to generate canonical gRPC service bindings, implementing Health v1, Reflection v1, and Channelz v1 on top of transport’s immutable descriptor/diagnostics snapshots. This module requires explicit registration — adding the dependency alone won’t expose management endpoints.

binlog is also an explicitly-enabled standalone module. It captures canonical binary-log v1 events via a transport interceptor, controlling information exposure and memory limits through metadata/message truncation, sensitive key redaction, and fixed-capacity sinks.

interop-test introduces grpc-java in test scope. grpc-java serves as the compatibility oracle here, never entering the project runtime.

Dependency Selection and Version Pinning

The runtime dependency chain is intentionally kept short:

The project does not introduce Spring, Micrometer, or any DI framework. Tests use JUnit 6.1.2 and Reactor Test’s StepVerifier. grpc-java 1.82.2 appears only in interop-test‘s test classpath with zero runtime intrusion.

Versions are centrally managed via gradle/libs.versions.toml with Gradle dependency locking generating lock files, ensuring fully reproducible builds across machines.

Why the Protocol Layer Must Come First

It’s tempting to start with “spin up an HTTP/2 Server” — you quickly get an echo demo, but it pushes the truly difficult problems to later:

• DATA may split in the middle of the five-byte gRPC header;
• A single DATA buffer may contain multiple messages;
• Metadata allows duplicate keys, and binary values require Base64;
• Timeout wire values are at most eight digits with a unit suffix;
• Final status comes from trailers;
• ByteBuf must be released on success, failure, and cancellation paths;
• Reactive Streams demand counts messages, HTTP/2 flow control counts bytes.

Therefore the project progresses by Stage: first lock down the build and interop fixtures, then complete the protocol layer, then implement unary transport, streaming, production features, and codegen. Each Stage has executable exit criteria — “classes have been created” is not a completion standard.

Stage 0: Build Baseline and Interop Fixture

Before writing any protocol code, Stage 0 solves “how to prove code is correct”:

JDK 25 compilation — The project uses -Xlint:all -parameters -encoding UTF-8 for strict compilation. All warnings are compilation errors; silent suppression is not allowed. JDK 25 was chosen to validate Netty and Protobuf compatibility on the latest JVM early.

Spotless formatting — Unified Eclipse formatter config plus ktlint. spotlessCheck is the first gate in CI. This eliminates all code review discussions about formatting.

interop.proto test fixture — Defines a test service covering all four RPC cardinalities:

1
2
3
4
5
6

service InteropTestService {
  rpc Unary (TestRequest) returns (TestResponse);
  rpc ServerStreaming (TestRequest) returns (stream TestResponse);
  rpc ClientStreaming (stream TestRequest) returns (TestResponse);
  rpc BidirectionalStreaming (stream TestRequest) returns (stream TestResponse);
}

GrpcJavaFixture — In the interop-test module, a test utility class starts both a grpc-java server and client, providing start() / close() lifecycle. Through it, bidirectional verification is possible: Reactor client calls grpc-java server, and grpc-java client calls Reactor server. Both use the same .proto generated code, ensuring wire compatibility.

Utilities:

• FreePorts: Allocates independent ports for each test, avoiding parallel test conflicts;
• TlsTestCertificates: Pre-generates self-signed certificates for subsequent TLS tests;
• LeakDetection: Integrates Netty’s ResourceLeakDetector, ensuring ByteBuf leaks are immediately exposed in tests.

Stage 0 exit criteria: ./gradlew clean test passes from fresh checkout, CI is green on Linux + Java 25, protoc generation is deterministically reproducible, grpc-java fixture communicates bidirectionally.

Staged Verification Strategy

The project progresses through 12 Stages, each with clear goals, executable exit criteria, and regression coverage:

Each Stage completion requires: ./gradlew clean spotlessCheck test --no-daemon passes in full, and all prior Stage tests continue running as regression. This means when Stage 4 completes, Stage 2’s unary tests are still green.

Where Reactor semantics differ from grpc-java

The wire contract is shared, but the application contracts are not. The tests therefore compare the two implementations at the protocol boundary and test each runtime’s lifecycle rules separately:

For example, the Reactor demand test starts with zero demand and asks for one response at a time:

1
2
3
4
5
6
7

StepVerifier.create(client.bidirectionalStreaming(BIDI, requests), 0)
        .thenRequest(1)
        .expectNext(first)
        .thenRequest(2)
        .expectNext(second, third)
        .expectComplete()
        .verify();

The corresponding grpc-java test uses StreamObserver callbacks and completion signals. The messages and trailers must be wire-compatible, but it would be incorrect to describe the two tests as asserting the same backpressure mechanism. This distinction is why the project keeps both cross-runtime interop and runtime-specific failure tests.

The repository now also has two server-streaming cancellation interop cases in ServerStreamingInteroperabilityTest: a Reactor client receives one response from a grpc-java server and cancels, while a grpc-java client cancels a Reactor server after its first response. Both sides wait for the peer’s cancellation callback under paranoid leak detection. The lower-level GrpcFrameCodecTest keeps the direct ownership assertion by checking that cancelled and partial inputs finish with refCnt() == 0.

The essential cancellation paths are deliberately small:

1
2
3
4
5
6
7
8
9
10
11
12

// Reactor client: cancel the HTTP/2 call after the first response.
TestResponse first = reactorStub
        .serverStreaming(Mono.just(request(5)))
        .take(1)
        .single()
        .block(Duration.ofSeconds(5));

// grpc-java client: cancel from the response callback.
@Override
public void onNext(TestResponse response) {
    requestStream.cancel("cancel after first response", null);
}

On the grpc-java server side, the test installs setOnCancelHandler; on the Reactor server side, the response Flux uses doOnCancel. The complete test, including latches, peer status assertions, shutdown, and leak-detection scope, is in ServerStreamingInteroperabilityTest.java.

Current Verification Results

The project uses this unified gate that simultaneously checks formatting, compilation, protocol tests, transport tests, and grpc-java interop tests:

1

./gradlew clean spotlessCheck test --no-daemon

This command passes as of this writing. The gate now includes the optional Stage 10 load-balancing extension tests in addition to protocol, transport, codegen, services, binary-log, and grpc-java interop tests. The dependency baseline is Protobuf 4.35.1, grpc-java 1.82.2, and JUnit 6.1.2. Under JDK 25, you’ll still see Protobuf Unsafe, Netty/Gradle native access, and Gradle deprecated feature warnings — they don’t affect test results but need ongoing tracking through future JDK and Gradle upgrades.

Subsequent posts will continue discussing the five-byte gRPC message envelope, ByteBuf ownership, four RPC cardinalities, production transport, DNS, code generation, standard management services, and how to integrate interceptors, observation, and binary logging without breaking Reactive Streams semantics.

这不是为了证明 grpc-java 不好。grpc-java 已经成熟、稳定，并覆盖负载均衡、NameResolver、重试和丰富的可观测性。这个项目要回答的是另一个问题：如果应用的编程模型本来就是 Reactor，能否让 Mono 和 Flux 从生成 API 一直贯穿到 HTTP/2 stream，而不是在两套异步抽象之间适配？

本文基于 JDK 25、Gradle 9.2.1、Reactor 3.8.6、Reactor Netty 1.3.6 和 Netty 4.2.15.Final。main 已完成 Stage 0 到 Stage 10：在协议、四种 RPC cardinality、生产传输、DNS、codegen、标准服务和 Stage 9 加固之外，Stage 10 又加入了可选的负载均衡扩展制品，支持 grpclb、RLS、负载报告和 ORCA。

API 目标不是包装 StreamObserver

Protobuf 方法有四种 cardinality，目标 API 直接映射为：

为什么 gRPC 要定义四种而不是只做 unary？本质上这是请求和响应各自独立选择”单值还是流”的 2x2 组合：

它们解决不同场景：unary 覆盖经典 request-response；server streaming 用于服务端推送（事件订阅、大数据分页拉取）；client streaming 用于客户端批量上传（文件分片、批量写入）；bidirectional streaming 用于实时双向通信（聊天、协同编辑）。这不是凭空发明的四种模式——HTTP/2 stream 本身就是全双工的，单个连接可以多路复用数百条并发 stream，请求和响应都可以独立发送多帧数据。gRPC 把这种传输能力提升为一等 API 语义：不是 chunked transfer encoding 的变体，而是让编译器在类型层面检查调用方和实现方是否匹配。

低层传输只保留一个统一模型：

1

Flux<Req> -> HTTP/2 stream -> Flux<Resp>

生成代码负责在边界应用 single() 等 cardinality 检查。这样不需要为四种 RPC 分别实现四套网络逻辑，也能明确拒绝 unary 空请求、重复请求或重复响应。

兼容的是 wire protocol

项目的兼容目标是公开的 gRPC over HTTP/2 协议规范，不是 grpc-java 内部 API：

1
2
3
4
5
6
7
8
9

generated Reactor API
        |
call dispatcher / service registry
        |
marshaller + message framer/deframer
        |
metadata + status + deadline
        |
Reactor Netty HTTP/2 stream

每个 RPC 对应一个 HTTP/2 stream。请求以 HEADERS frame 开始，至少包含：

1
2
3
4
5

:method      POST
:path        /<package.Service>/<Method>
content-type application/grpc+proto
te           trailers
grpc-timeout <相对超时，如 100m 表示 100ms>

消息体使用 Length-Prefixed-Message 格式封装在 DATA frame 中——每条 Protobuf 消息前有五字节 envelope（1 字节压缩标志 + 4 字节大端长度）。一个 DATA frame 可能包含多条 gRPC 消息，一条大消息也可能跨越多个 DATA frame。

为什么 gRPC 必须依赖 HTTP trailers？ 这是协议最反直觉的设计之一。HTTP status code 对 gRPC 来说几乎无用——协议要求 HTTP 层始终返回 200，真正的调用结果（grpc-status 和 grpc-message）放在 trailers 中。原因在于：streaming 场景下，server 可能已经发送了数千条消息，最终成功还是失败只有处理完最后一条数据后才能确定。HTTP headers 在 body 之前发送，无法承载这个后验结果。trailers 是 HTTP/2 中唯一可以在 body 之后附加 metadata 的机制。

协议还定义了 trailers-only 模式：当 server 在读取 body 之前就能判定失败（比如路径不存在、认证失败），grpc-status 直接放在 response headers 中返回，不发送 body，节省一次 round-trip。Client 必须同时检查 headers 和 trailers 两个位置才能正确提取最终状态。

按协议边界拆模块

项目目前有九个模块：

1
2
3
4
5
6
7
8
9

grpc-reactor-protocol      → 与传输无关的协议原语
grpc-reactor-transport     → Reactor Netty HTTP/2 映射
grpc-reactor-codegen       → Protoc 插件，生成 Reactor stub
grpc-reactor-gradle-plugin → Gradle 集成
grpc-reactor-maven-plugin  → Maven generate-sources 集成
grpc-reactor-services      → 可选 Health、Reflection 与 Channelz 标准服务
grpc-reactor-binlog        → 可选、有界的 canonical binary logging
grpc-reactor-lb-extensions → 可选 grpclb、RLS、负载报告与 ORCA
grpc-reactor-interop-test  → grpc-java 兼容性测试

protocol 只处理与传输无关的值和编解码：消息帧、metadata、status、timeout、compression 和 protobuf marshaller。它依赖 Reactor Core 与 Netty Buffer，但不依赖 Reactor Netty——这意味着协议层可以独立测试而不需要真实的 HTTP/2 连接。

transport 把协议映射到 Reactor Netty HTTP/2，负责 client、server、service registry 和 per-call context。

codegen 消费 Protobuf CodeGeneratorRequest，生成类型安全的 Reactor client 和 service binder。

services 使用同一套 codegen 生成 canonical gRPC service binding，并在 transport 的 immutable descriptor/diagnostics snapshot 之上实现 Health v1、Reflection v1 和 Channelz v1。该模块需要显式注册，不会因为加入依赖就自动暴露管理端点。

binlog 同样是显式启用的独立模块。它以 transport interceptor 捕获 canonical binary-log v1 event，通过 metadata/message 截断、敏感 key 脱敏和固定容量 sink 控制信息暴露与内存上限。

interop-test 在测试作用域引入 grpc-java。grpc-java 在这里是兼容性判定器，不进入项目运行时。

依赖选型与版本锁定

运行时依赖链刻意保持短小：

项目不引入 Spring、Micrometer 或任何 DI 框架。测试使用 JUnit 6.1.2 与 Reactor Test 的 StepVerifier。grpc-java 1.82.2 仅出现在 interop-test 的 test classpath，运行时零侵入。

版本通过 gradle/libs.versions.toml 集中管理，配合 Gradle dependency locking 生成锁文件，确保不同机器的构建完全可复现。

为什么协议层必须先完成

直接从”启动一个 HTTP/2 Server”开始很容易得到一个能 echo 的演示，却会把真正困难的问题推迟：

• DATA 可能在五字节 gRPC header 中间分片；
• 一个 DATA buffer 可能包含多条消息；
• metadata 允许重复键，二进制值需要 Base64；
• timeout wire value 最多八位并带单位；
• 最终状态来自 trailers；
• ByteBuf 在成功、失败和取消路径都必须释放；
• Reactive Streams demand 以消息计数，HTTP/2 flow control 以字节计数。

因此项目按 Stage 推进：先固定构建和互操作 fixture，再完成协议层，之后才实现 unary transport、streaming、生产特性和 codegen。每个 Stage 都有可执行退出条件，不以”类已经创建”作为完成标准。

Stage 0：构建基线与互操作 fixture

在写任何协议代码之前，Stage 0 解决的是”如何证明代码正确”：

JDK 25 编译配置——项目使用 -Xlint:all -parameters -encoding UTF-8 严格编译。所有警告都是编译错误，不允许静默忽略。选择 JDK 25 是为了提前验证 Netty 和 Protobuf 在最新 JVM 上的兼容性。

Spotless 格式化——统一使用 Eclipse formatter 配置加 ktlint，spotlessCheck 是 CI 门禁的第一道关。这消除了所有关于格式的 code review 讨论。

interop.proto 测试 fixture——定义了包含全部四种 RPC cardinality 的测试 service：

1
2
3
4
5
6

service InteropTestService {
  rpc Unary (TestRequest) returns (TestResponse);
  rpc ServerStreaming (TestRequest) returns (stream TestResponse);
  rpc ClientStreaming (stream TestRequest) returns (TestResponse);
  rpc BidirectionalStreaming (stream TestRequest) returns (stream TestResponse);
}

GrpcJavaFixture——在 interop-test 模块中，一个测试工具类同时启动 grpc-java server 和 client，提供 start() / close() 生命周期。通过它可以双向验证：Reactor client 调用 grpc-java server，以及 grpc-java client 调用 Reactor server。两者使用相同的 .proto 生成代码，确保 wire 兼容。

辅助工具：

• FreePorts：为每个测试分配独立端口，避免并行测试冲突；
• TlsTestCertificates：为后续 TLS 测试预生成自签名证书；
• LeakDetection：集成 Netty 的 ResourceLeakDetector，确保 ByteBuf 泄漏在测试中立即暴露。

Stage 0 退出条件：./gradlew clean test 从 fresh checkout 通过，CI 在 Linux + Java 25 绿灯，protoc 生成确定性可重现，grpc-java fixture 双向通信正常。

分阶段验证策略

项目按 12 个 Stage 递进，每个 Stage 有明确的目标、可执行退出条件和回归保障：

每个 Stage 完成时必须满足：./gradlew clean spotlessCheck test --no-daemon 全量通过，且前序 Stage 的测试作为回归继续运行。这意味着 Stage 4 完成时，Stage 2 的 unary 测试仍然是绿的。

Reactor 与 grpc-java 的语义差异

两套实现共享 wire protocol，但应用层契约并不相同。互操作测试验证消息、状态和 metadata 能跨实现传输；运行时测试则分别验证各自的生命周期规则，不能把两者简单视为同一种背压或取消机制：

例如，Reactor 的双向流测试从零 demand 开始，逐批请求响应：

1
2
3
4
5
6
7

StepVerifier.create(client.bidirectionalStreaming(BIDI, requests), 0)
        .thenRequest(1)
        .expectNext(first)
        .thenRequest(2)
        .expectNext(second, third)
        .expectComplete()
        .verify();

对应的 grpc-java 测试使用 StreamObserver callback 和完成信号。消息与 trailers 必须 wire-compatible，但两套测试断言的背压机制并不相同；这也是项目同时保留跨实现互操作测试和运行时故障测试的原因。

仓库现在还在 ServerStreamingInteroperabilityTest 中加入了两个 server streaming 取消互操作案例：Reactor client 从 grpc-java server 收到一条响应后取消，以及 grpc-java client 在收到 Reactor server 的第一条响应后取消。两侧都在 paranoid leak detection 下等待对端的取消 callback；更底层的 GrpcFrameCodecTest 则直接断言取消和 partial frame 输入最终达到 refCnt() == 0。

核心取消路径其实很短：

1
2
3
4
5
6
7
8
9
10
11
12

// Reactor client：收到第一条响应后取消 HTTP/2 调用
TestResponse first = reactorStub
        .serverStreaming(Mono.just(request(5)))
        .take(1)
        .single()
        .block(Duration.ofSeconds(5));

// grpc-java client：在响应 callback 中取消
@Override
public void onNext(TestResponse response) {
    requestStream.cancel("cancel after first response", null);
}

grpc-java server 通过 setOnCancelHandler 观察取消，Reactor server 则在响应 Flux 上使用 doOnCancel。包含 latch、对端状态断言、资源关闭和 leak detection 的完整代码见 ServerStreamingInteroperabilityTest.java。

当前验证结果

项目统一使用下面的完整门禁，同时检查格式、编译、协议测试、transport 测试和 grpc-java 互操作测试：

1

./gradlew clean spotlessCheck test --no-daemon

本文更新时该命令已经通过。当前门禁除了协议、transport、codegen、标准服务、binary-log 和 grpc-java 互操作测试外，也包含 Stage 10 负载均衡扩展测试。依赖基线是 Protobuf 4.35.1、grpc-java 1.82.2 和 JUnit 6.1.2。JDK 25 下仍会看到 Protobuf Unsafe、Netty/Gradle native access 与 Gradle deprecated feature 提示，它们不影响本次测试结果，但需要在后续 JDK 和 Gradle 升级时持续跟踪。

后续文章将继续讨论五字节 gRPC message envelope、ByteBuf 所有权、四种 RPC cardinality、生产传输、DNS、代码生成、标准管理服务，以及如何在不破坏 Reactive Streams 语义的前提下接入 interceptor、观测与 binary log。