Grpc Knowledge Patch

gRPC Knowledge Patch

Apply this skill when changing gRPC transports, generated tooling, Python servers, Go authorization, Java channels, xDS, or load-balancing behavior.

Working method

1. Identify the implementation, package versions, transport, and deployment platform involved in the task.
2. Read the matching reference before relying on a security default, dependency bound, xDS matcher, or dynamically created channel.
3. Treat default changes as behavior changes even when application code did not opt in explicitly.
4. Preserve intentional compatibility overrides until integration and interoperability tests show that they are no longer needed.
5. Exercise success and failure paths for interceptors, name resolution, authorization, connection setup, and control-plane resource loading.
6. Prefer project manifests, lockfiles, code, tests, and observed runtime behavior when they conflict with general assumptions.

Reference index

Breaking changes, defaults, and compatibility risks

TLS negotiation changes without an opt-in

• Expect new gRPC Core TLS connections to use post-quantum cryptography in key exchange by default.
• Recheck TLS inspection, policy enforcement, interoperability, and latency assumptions even when application TLS configuration is unchanged.
• On Android, account for TLS 1.3 on OkHttp-based gRPC Java servers as well as clients.
• Read transport security and tooling before changing TLS policy or transport dependencies.

Java URI parsing follows RFC 3986 by default

• Re-test targets containing reserved characters, percent escapes, unusual authorities, or path-like components.
• Keep target-parsing tests close to custom resolvers and channel construction.
• Do not infer legacy parsing behavior from the absence of an application opt-in.

gRPC-Go throttles HTTP/2 control-frame floods

• Expect the server to stop reading from a connection when the control-frame limit is reached.
• The default limit is 100 frames; DATA and HEADERS frames do not count.
• Change the limit only through GRPC_GO_EXPERIMENTAL_CONTROL_BUFFER_THROTTLE_LIMIT, then validate legitimate high-control-frame traffic as well as abusive traffic.

export GRPC_GO_EXPERIMENTAL_CONTROL_BUFFER_THROTTLE_LIMIT=200

Go xDS authorization closes fail-open paths

• Treat Metadata and RequestedServerName as enforced permission fields in gRPC-Go xDS RBAC rules, including DENY rules.
• Validate and canonicalize header names in nested Principal and Permission rules; non-lowercase names are covered by the same handling.
• Reject :scheme and grpc--prefixed matchers, and map host to :authority.
• Re-test mixed-case header matchers so they cannot silently match nothing and let a DENY rule fail open.
• Continue accepting deprecated source_ip principals as equivalent to direct_remote_ip, but emit the current spelling in new configuration.

Netty enforces stream limits during connection setup

• Expect the gRPC-Java Netty server to enforce its client-initiated stream limit from startup, before SETTINGS_ACK arrives.
• Test connection startup as well as steady-state multiplexing when clients approach or exceed the configured limit.

Java xDS control-plane connections are channel-scoped

• Do not assume that xDS control-plane connections are reused across channels.
• With many targets, compare channel resolution progress with the control plane's MAX_CONCURRENT_STREAMS; exhausted streams can leave new channels waiting for resources.
• Capacity-test the production-like number of channels and targets.

Python protobuf compatibility has two paths

• Treat 7.35.1 as the lower bound for the main Python protobuf dependency.
• Do not apply that bound to the separate v1.83.x grpc-status backport; its relaxed bound retains protobuf 6.x compatibility.
• Identify which package constrains protobuf before changing a lockfile.

Aggregate-cluster metric labels identify the leaf

• Expect gRPC-Java xDS metrics for aggregate clusters to use the leaf cluster name as the backend-service label.
• Update dashboards, alerts, joins, and cardinality expectations that grouped these metrics by aggregate cluster name.

New APIs and capability quick reference

Abort async Python RPCs with a status object

Use the status-based abort method directly from grpc.aio.ServicerContext:

async def handle(request, context):
    await context.abort_with_status(status)

The method is part of the abstract async context interface. Keep custom context implementations compatible and verify that awaited aborts end handler control flow as expected.

Isolate Java name resolution per channel

Use the Grpc.newChannelBuilder overload that accepts a NameResolverRegistry when a channel should use an explicitly supplied registry instead of process-global resolver state.

Customize dynamically created Java child channels

Use ChildChannelConfigurer to intercept child channels created by load balancers. Apply channel-specific interceptors or credential changes there, then verify the resulting dynamic channels.

Accept ordinary Java numeric service-config values

Pass integer-looking values such as maxAttempts: 4 and backoffMultiplier: 2 to defaultServiceConfig() without first converting them to decimal literals. Validation accepts any Number and normalizes accepted values to Double.

Select ORCA metrics for LRS propagation

Expect ORCA-to-LRS propagation to be enabled by default in gRPC Java. Under gRFC A85, use xDS configuration to select which fields from backend ORCA metric reports are propagated into LRS load reports.

Use current Python and Linux ARM64 support

• Include Python 3.15 in supported-runtime testing when the application adopts that interpreter.
• On Linux ARM64, account for the Grpc.Tools move to manylinux_2_28 and the maximum-page-size alignment fix for its bundled protoc.
• Re-evaluate the build-image baseline when upgrading tooling, even if the generated source does not change.

Implementation checklists

Transport and packaging

• Read transport-security-and-tooling.md.
• Exercise TLS handshakes against every relevant peer and intermediary.
• Load-test the HTTP/2 control-frame threshold before overriding it.
• Test Netty's client-initiated stream limit during connection setup.
• Run the packaged protoc on the actual Linux ARM64 build image.
• Verify Android server and client TLS expectations separately.

Python

• Read python-apis-runtime-and-dependencies.md.
• Inspect both the main gRPC and grpc-status dependency paths before resolving protobuf constraints.
• Await status-based aborts and update custom async contexts.
• Test interceptor exceptions for every unary or streaming call shape in use.
• Add Python 3.15 to CI only after native and generated dependencies agree.

Go authorization and server protection

• Read authorization-and-xds.md and the Go section of transport-security-and-tooling.md.
• Re-run DENY-policy tests for metadata and requested server names.
• Test valid, remapped, mixed-case, and forbidden header names in nested rules.
• Accept legacy source_ip input while emitting direct_remote_ip in new xDS configuration.
• Observe behavior at the default flood threshold before tuning it.

Java channels, xDS, and load balancing

• Read java-channel-and-configuration.md for channel construction and parsing.
• Read authorization-and-xds.md for xDS telemetry, labels, and control-plane connection behavior.
• Test custom targets under RFC 3986 parsing.
• Supply a channel-local resolver registry where global state is inappropriate.
• Verify interceptors and credentials on dynamically created child channels.
• Update metric queries to use leaf-cluster backend-service labels.
• Stress resource loading with a production-like number of channels and targets.
• Exercise Netty stream limits before and after connection setup completes.

Validation matrix

Load only the indexed references relevant to the implementation, then retain their implementation-specific checks in code review and regression tests.