gRPC · XB Field Notes

Protobuf evolution preserves meaning only within a defined contract

Sat, 26 Feb 2028 00:00:00 +0000

A gRPC rollout can leave old producers, new consumers, and intermediate services running together. Protobuf helps them exchange binary messages by identifying fields with numbers and wire types. That tolerance is narrower than application compatibility: a message can parse successfully while a consumer misunderstands its values, ignores a new instruction, or loses the distinction between absent and explicitly zero.

Separate numbers, meaning, and bytes

A binary tag combines the field number with its wire type; the field name is not transmitted there. Keeping the number and type while renaming a field can preserve binary decoding. It still changes generated accessors and may change JSON or text interfaces. A gRPC method name or service name belongs to another contract and is not protected by a field-number rule.

Never reuse a retired number for another meaning. Different declared types can share a wire type: signed and unsigned integers both use varints, yet a negative signed value can become a large unsigned value. A successful parse is therefore insufficient validation. Reserve retired numbers and names in the schema so later declarations cannot accidentally reclaim them; reserved numbers are unavailable, not placeholders to activate later.

Unknown fields can survive a parse-and-serialize binary relay. However, copying only known fields or converting through JSON can discard them. Preservation of decoded information also does not promise byte-identical serialization. Field order and encoding choices can differ, including across implementations. Compare required values and presence in compatibility tests; do not use ordinary reserialization as a canonical digest algorithm.

Presence carries a separate bit of meaning

In proto3, singular scalar fields without optional generally use implicit presence. Their default value is indistinguishable from absence through the normal API. Explicit optional scalars track whether a value was supplied, including zero. Message fields and oneof members already have presence; repeated and map fields do not distinguish an empty collection from an absent one.

Changing a scalar between implicit and explicit presence can remain binary-readable while changing round-trip semantics. An older reader that knows the field with implicit presence can parse explicit zero and then omit it when forwarding. Adding optional at one endpoint cannot force every intermediary to preserve that distinction. Test the entire path that actually modifies or forwards the message.

When it breaks

A new consumer may require a field that old writers never supplied. Although proto3 has no required declaration, application validation can create exactly this rolling-upgrade failure. Introduce an agreed fallback or sequence the rollout before enforcing the requirement. Optional syntax alone does not define a sensible default, authorize an operation, or make an old service implement a new feature.

Also test persisted messages, delayed jobs, and rollback versions. Their useful lifetime can exceed the deployment window. A schema check against only the immediately previous release misses older records that can still reappear. Keep retired numbers reserved even when current traffic no longer uses them.

Both relayed results return zero, but the unknown-field relay retains explicit presence while the known implicit-presence relay loses it. The historical Python fixture passed within its local scope; it did not test reserved declarations, real gRPC calls or cross-language clients. No example was rerun for this drawing.

Check it quickly

Run the complete block with Python and Google’s protobuf package 7.36.2 available. It was executed with Python 3.12.14. Separate descriptor pools create real old and new message classes without a compiler, filesystem fixture, gRPC server, or network connection. This checks the Python binary runtime, not cross-language interoperability or generated-client compatibility.

from google.protobuf import descriptor_pb2 as schema, descriptor_pool, message_factory


def message(fields, explicit=()):
 file = schema.FileDescriptorProto(name='probe.proto', package='probe', syntax='proto3')
 record = file.message_type.add(name='Record')
 for name, number, kind in fields:
 field = record.field.add(name=name, number=number, type=kind, label=1)
 if name in explicit:
 field.oneof_index = len(record.oneof_decl)
 record.oneof_decl.add(name='_' + name)
 field.proto3_optional = True
 pool = descriptor_pool.DescriptorPool()
 pool.Add(file)
 return message_factory.GetMessageClass(pool.FindMessageTypeByName('probe.Record'))


INT32 = schema.FieldDescriptorProto.TYPE_INT32
UINT32 = schema.FieldDescriptorProto.TYPE_UINT32
STRING = schema.FieldDescriptorProto.TYPE_STRING
Old = message([('id', 1, INT32), ('name', 2, STRING)])
New = message([('event_id', 1, INT32), ('name', 2, STRING), ('count', 3, INT32)], ('count',))
Implicit = message([('event_id', 1, INT32), ('name', 2, STRING), ('count', 3, INT32)])

old = Old(id=7, name='alpha')
new_reader = New.FromString(old.SerializeToString())
assert new_reader.event_id == 7 and not new_reader.HasField('count')
# The added explicit zero is unknown to Old but retained in binary forwarding.
new_writer = New(event_id=7, name='alpha', count=0)
relay = Old.FromString(new_writer.SerializeToString())
returned = New.FromString(relay.SerializeToString())
assert returned.event_id == 7 and returned.HasField('count') and returned.count == 0
print('old/new binary values survive; unknown explicit zero survives the old relay')

# An implicit-presence reader knows field 3, so zero is omitted on serialization.
implicit_relay = Implicit.FromString(new_writer.SerializeToString())
lost_presence = New.FromString(implicit_relay.SerializeToString())
assert lost_presence.count == 0 and not lost_presence.HasField('count')
print('an implicit-presence relay preserves zero but loses its explicit presence')

Signed = message([('value', 1, INT32)])
Unsigned = message([('value', 1, UINT32)])
assert Unsigned.FromString(Signed(value=-1).SerializeToString()).value == 4294967295
# Distinct field order is legal; compare decoded meaning, not byte equality.
reordered = b'\x18\x00' + old.SerializeToString()
assert New.FromString(reordered) == new_writer
print('reusing an integer tag changes meaning; legal field orders decode equivalently')

The first output confirms that an old writer remains readable and that an unknown explicit zero survives the old binary relay. The next output exposes a different result when the relay knows that field with implicit presence: its value remains zero, but HasField becomes false after forwarding. These are different compatibility questions, not contradictory observations.

The final assertions decode negative one as 4294967295 under an incompatible unsigned interpretation and accept a legal alternative field order. They demonstrate why wire readability does not establish semantic equivalence or canonical bytes. The descriptor exercise does not compile reserved declarations; compiler checks and real gRPC request/response behavior remain separate rollout tests.

Sources

Protobuf: encoding, tags, varints and serialization ordering, checked 2026-10-15.
Protobuf: proto3 language guide, binary changes, reserved fields and unknown-field retention, checked 2026-10-15.
Protobuf: field presence, implicit and explicit presence across relays, checked 2026-10-15.
Protobuf: dos and don’ts, retired numbers and compatibility discipline, checked 2026-10-15.

gRPC multiplexes many streams over one HTTP/2 connection

Sat, 16 Jan 2027 00:00:00 +0000

gRPC’s HTTP/2 transport lets multiple RPC attempts share a connection while keeping each stream’s messages ordered. That is useful for both short calls and long-lived exchanges. It does not make the connection an unlimited independent transport for every call: bandwidth, TCP delivery, connection flow control, and implementation resources remain shared.

Match the RPC shape to the work

An HTTP/2 RPC attempt occupies a stream; a retry starts another attempt rather than replaying bytes into a completed stream. Reusing connections amortizes establishment and TLS costs, but a channel can manage multiple connections. Calls to different backends do not all magically share one TCP endpoint, and per-call costs still include serialization, metadata, framing, scheduling, and application work.

gRPC offers unary, client-streaming, server-streaming, and bidirectional-streaming methods. Only the last permits independent sequences of messages in both directions within the same RPC. Message ordering is preserved within each direction, without requiring one response per request message. Choose that shape when the application needs it, rather than assuming every gRPC method streams both ways.

HTTP/1.1 can reuse persistent connections, and WebSocket already supports bidirectional messages. Neither inherently needs a fresh handshake for every application message. gRPC’s advantages instead include its RPC contract, generated interfaces, status model, and HTTP/2 stream multiplexing. Compare complete workloads and operational constraints before claiming that streaming is universally faster or requires less buffering.

Separate call deadlines from shared transport

A deadline belongs to an RPC, not automatically to every stream on its connection. Propagate the remaining budget into downstream calls using the language’s supported context mechanism. Starting a fresh full timeout at each hop can extend work beyond the caller’s willingness to wait. Cancellation also needs cooperation from application work; it does not undo effects already committed.

Flow control has both stream and connection scopes for DATA frames. An exhausted stream window can stop that stream while siblings progress if connection credit remains available. Exhausted connection credit prevents nonempty DATA across streams in that direction; zero-length DATA with END_STREAM and control frames can still be sent. Receiver implementations can replenish connection credit independently, so one slow reader does not inevitably exhaust the entire connection.

TCP packet loss can still delay delivery shared by multiple HTTP/2 streams. Queues, CPU, and memory also create coupling outside the protocol’s stream abstraction. A successful write into a library buffer does not establish remote delivery or application consumption. Bound buffers and test slow-reader behavior in the actual client and server libraries.

When it breaks

Oversized metadata can exceed an implementation or proxy limit before the handler runs. The gRPC guide suggests an eight-kibibyte default request-header limit, not a universal maximum or one guaranteed failure status. Inspect both endpoints and intermediaries, and avoid assuming that resending unchanged metadata will fix rejection.

A long-lived stream remains on its selected backend. Connection-level load balancing can concentrate many streams, and reaching concurrent-stream limits may queue new calls rather than create another connection. Choose supported client or proxy balancing deliberately; changing connection lifetime or stream limits is not proof of redistribution. Observe backend occupancy and reconnect behavior before tuning.

gRPC shared flow control: mechanism and evidence boundaries.

Check it quickly

Save this as mux_sim.py and run python3 mux_sim.py. The standard-library model uses three ordered queues with separate stream and connection credits. Each message costs one invented unit; these are not encoded HTTP/2 frames or actual byte windows. Use assertions enabled, without -O or PYTHONOPTIMIZE: pump calls inside assert are part of the scenario. Odd stream identifiers resemble the client side without implementing the wire protocol.

from collections import deque

original = {1: ["a1", "a2", "a3"], 3: ["b1", "b2", "b3"], 5: ["c1", "c2"]}
streams = {sid: deque(items) for sid, items in original.items()}
credit = {1: 3, 3: 3, 5: 2}
connection_credit = 8
wire = []
delivered = {sid: [] for sid in streams}

def pump():
 global connection_credit
 progressed = False
 for sid in sorted(streams):
 if streams[sid] and credit[sid] > 0 and connection_credit > 0:
 payload = streams[sid].popleft()
 credit[sid] -= 1
 connection_credit -= 1
 wire.append((sid, payload))
 delivered[sid].append(payload)
 progressed = True
 return progressed

def drain():
 while pump():
 pass

assert pump()
assert wire == [(1, "a1"), (3, "b1"), (5, "c1")]
credit[3] = 0 # Model a receiver withholding this stream's credit.
drain()
assert delivered[1] == original[1] and delivered[5] == original[5]
assert delivered[3] == ["b1"] and len(wire) == 6
assert connection_credit == 2

credit[3] = 2
connection_credit = 0 # Independent negative control: no connection capacity.
assert not pump() and delivered[3] == ["b1"]
connection_credit = 2
drain()
assert delivered == original and len(wire) == 8
assert connection_credit == 0 and all(not queue for queue in streams.values())
print("wire:", wire)
print("PASS: stream credit isolates one stall; connection credit gates all modeled data")

After one pass, withholding stream 3’s credit lets streams 1 and 5 complete while stream 3 retains two queued messages. Restoring only its stream credit is insufficient when the connection control is set to zero: no message advances. Restoring connection credit then drains all eight messages, with each stream retaining its original order.

Retained exact runs establish these model rules with assertions enabled; this source review did not rerun them. They do not test a gRPC library, HTTP/2 frame encoding, TCP loss, TLS, deadline propagation, cancellation, or balancing. Keep this small experiment separate from a real integration test that deliberately slows one consumer and records stream-level versus connection-level behavior.

Sources

Python assert statement, optimization omits assertions and any calls inside them, checked 2026-10-18.
gRPC core concepts, defines streams over HTTP/2, checked 2026-06-01.
RFC 9113: HTTP/2, streams, multiplexing, and flow control, checked 2026-09-09.
gRPC flow control, buffering and slow-reader boundaries, checked 2026-10-15.
gRPC deadlines, per-RPC budgets and propagation, checked 2026-10-15.
gRPC metadata, suggested header limits, checked 2026-10-15.
gRPC performance guidance, channels, concurrent-stream queues, and long-lived streaming limits, checked 2026-10-15.

gRPC · XB Field Notes

Protobuf evolution preserves meaning only within a defined contract

Separate numbers, meaning, and bytes

Presence carries a separate bit of meaning

When it breaks

Check it quickly

Sources

gRPC multiplexes many streams over one HTTP/2 connection

Match the RPC shape to the work

Separate call deadlines from shared transport

When it breaks

Check it quickly

Further reading

Sources