Java CodedInputStream: aliasing ergonomics + high-performance parsing documentation

[samrod13]

What language does this apply to?

Java

If it's a proto syntax change, is it for proto2 or proto3?
If it's about generated code change, what programming language?

Not a proto syntax change (applies to both proto2 and proto3 payloads since it’s runtime parsing behavior).

Describe the problem you are trying to solve.

We recently implemented a high throughput incremental parser for a large, nested protobuf payload (telemetry/metrics style structure: repeated “resource blocks”, each with repeated “scopes”, repeated “measurements”, and repeated key/value “attributes”). The goal was to parse and validate only a subset of fields while minimizing allocations and CPU overhead (avoid constructing the full generated message object graph).

We found that protobuf’s Java runtime (CodedInputStream) supports the necessary low level primitives (readTag, pushLimit/popLimit, skipField, etc.), but it is difficult to use correctly and safely for these workloads. In particular:

• Aliasing is hard to reason about and hard to use safely.
  There is an enableAliasing(boolean) API, but it’s not obvious:
  • when it actually takes effect (implementation dependent),
  • what the correctness constraints are (buffer lifetime/pinning),
  • and what guarantees exist around readBytes() and readByteBuffer()
• Stream backed decoding can’t safely alias.
  For stream backed decoders, aliasing is typically not possible because internal buffers are reused/refilled. This is currently implied by implementation details (e.g. StreamDecoder enableAliasing being a noop) rather than clearly expressed in API and docs.
• ByteBuffer views are especially risky.
  readByteBuffer() can return a ByteBuffer.slice() backed by the underlying array when aliasing is enabled (for array backed decoders). The code itself contains a TODO about making returned buffers read only. This indicates the current behavior is known to be risky: the buffer is mutable and stateful (position/limit), and it’s easy for callers to accidentally mutate it or misuse cursor state, causing subtle bugs.
• There isn’t a “how to do this” guide.
  We ended up learning patterns like the pushLimit/popLimit limit stack by reading internal code and trial/error. It’s not obvious to many developers why you must popLimit(oldLimit) after each nested message, or how the cursor advances through a length delimited field. This makes it harder than necessary to implement an incremental parser correctly.

We want to reduce friction for teams building allocation sensitive incremental parsers (telemetry/logs/metrics/event ingestion, etc.) while keeping protobuf’s correctness guarantees intact.

(We can’t share internal production code, but we can provide simplified snippets showing the relevant parsing patterns.)

Describe the solution you'd like

We’d like to propose a small set of Java runtime improvements split across focused PRs, so maintainers can review incrementally:

Proposed PR #1: Aliasing ergonomics and documentation in CodedInputStream (Java runtime)

Goals:

• Make aliasing behavior easier to understand and safer to use.
• Reduce “guessing” and reliance on implementation details.

Candidate changes (examples — we’d like maintainer feedback on API shape):

• Improve Javadoc and guidance around CodedInputStream.enableAliasing(boolean):
  • explain buffer lifetime requirements,
  • clarify which kinds of decoders can alias (array backed vs stream backed),
  • clarify interaction with readBytes() and readByteBuffer()
• Optionally add small introspection helpers such as:
  • supportsAliasing() (implementation capability),
  • isAliasingEnabled() (flag state),
  • and/or an explicit method like readBytesPossiblyAliased() to make “may alias” semantics visible at call sites.
• Add unit tests covering:
  • stream backed vs array backed behavior expectations,
  • correctness of returned values regardless of aliasing.

Proposed PR #2: Long form “High performance parsing” guide (docs only)

Goals:

• Provide a clear, official guide for incremental parsing using CodedInputStream.

Contents:

• Explain tag loops, skipping fields, and nested parsing using pushLimit/popLimit.
• Include ASCII art style diagrams showing the cursor (pos) advancing through a buffer and how pushLimit/popLimit forms a limit stack.
• Include guidance on “read bytes first vs decode UTF-8 immediately”:
  • when it helps (dedup/interning / high cardinality attributes),
  • pitfalls (UTF-8 validation, security considerations),
  • and how aliasing affects buffer lifetime
• Include a generic “telemetry style payload” case study section (no OTLP/OpenTelemetry specific code) that mirrors common real world nested/repeated payload shapes.

Proposed PR #3: Safer ByteBuffer views when aliasing is enabled

Goals:

• Reduce accidental misuse of aliased ByteBuffer views.

Options (seeking maintainer preference):

• Minimal behavior change: when readByteBuffer() returns a view into an underlying array, return it as asReadOnlyBuffer() (aligns with existing TODO).
• Alternatively (or additionally), add a new API that makes this contract explicit (e.g. readReadOnlyByteBuffer() / readByteBufferPossiblyAliasedReadOnly()), leaving existing behavior unchanged for compatibility.

Describe alternatives you've considered

• Use generated message parsing (parseFrom) and accept allocations.
  This was not viable for our ingestion workload where we parse large nested batches and only need certain fields. Full object graph allocation overhead dominated runtime/GC.
• Write custom decoding without protobuf runtime.
  This would be error prone and would lose protobuf’s correctness guarantees and compatibility benefits.
• Manually copy all bytes always.
  Works but defeats the purpose of aliasing/zero copy optimizations and increases allocations significantly.
• Keep improvements internal only.
  This would avoid upstreaming but leaves the ecosystem with the same discoverability/safety issues. We’d prefer to contribute improvements so other teams can avoid the same pitfalls.

Additional context

• This request is motivated by implementing a production incremental parser for a nested, telemetry style protobuf payload with very high repetition of small strings (attribute keys/values) and large repeated arrays of messages.
• The runtime already supports the needed primitives, the primary issues are:
  • discoverability/documentation of correct patterns,
  • clearer aliasing semantics/capabilities,
  • and safer handling of ByteBuffer views (read only enforcement)
• We can provide simplified code snippets (generic parsing loops with pushLimit/popLimit) and performance/GC rationale, but we cannot share internal code verbatim due to legal review requirements.

Add any other context or screenshots about the feature request here.

[esrauchg]

Thanks for reaching out about this.

We can take a look at the PRs over the next couple weeks, I can provide some very high level initial feedback up front though.

he goal was to parse and validate only a subset of fields while minimizing allocations and CPU overhead (avoid constructing the full generated message object graph).

One technique you may want to consider if you're going down this rabbit hole is actually just to make what we refer to as 'overlay messages'. Since the wire format doesn't encode names anywhere, you can make smaller messages that are targeted subsets of some very large message and it will be parse/serialize compatible with the large message definition. You can use this technique to e.g. parse some large things while ignoring everything else (especially when combined with discard unknown on CodedInputStream).

In general CodedInputStream methods is mostly viewed as an implementation detail class rather than as a part of the public API that users are expected to use (as in: users are expected to construct one, but we expect gencode to be what is calling readBytes() for example).

There's not really technical mechanisms for us to create classes that are 'gencode support library only' where gencode can use it but application code cannot (gencode is effectively code authored by 'us', but where its in a user-controlled package and where we don't have visibility into what stale gencode customers may or may not be using).

That said, since it is public anyway it is still somewhat of a 'real' advanced api surface and so we wouldn't just wontfix this request, I'm mostly setting some ground premise about how far we might go re: documentation and recommending that people use this api surface. It also may explain some of the quirks you're seeing about safety here.

There is an enableAliasing(boolean) API, but it’s not obvious:

Aliasing is more well established on our C++ API than our Java one, but the semantic is generally "the implementation may alias bytes and string fields, but makes no guarantees and it would always be considered correct behavior to ignore the alias enabling". In Java all that it will ever do is have some subset of strings/bytes fields with the a byte[] reference to what was passed in (which may be the backing array of a ByteBuffer verbatim).

In both cases we generally can only alias if parsing out from one flat input since streaming inputs don't tend to have any owned chunks that would be live.

In general, aliasing in JavaProto is not super well trodden in part because it doesn't give the wins that people seem to expect (your case may be an exception though). For some similar context, java.lang.String.substring() used to just alias the previous String (and was fully safe because they are all immutable), and about a decade ago Oracle realized this was a net pessimization compared to copying on every substring call, in terms of keeping large strings alive and having extra bounds compared to the underlying data array.

[samrod13]

@esrauchg Thanks for the detailed response.

Overlay Messages

I’ll try this path and see how far it gets me before investing too heavily in lower level parsing.

CodedInputStream being "implementation detail-ish"

Understood on the premise that CodedInputStream is not an API you necessarily want to recommend as an application level parsing surface (even if it’s public and used by generated code). That framing explains a lot of the existing quirks and why some areas (especially aliasing) feel under documented or “best effort”.

Given that, I’ll be careful to keep any docs PRs positioned as “advanced / internal parsing patterns used by generated code and power users”, not as a recommended default over generated messages. I’ll also explicitly call out overlay messages as the preferred approach before reaching for manual parsing.

Aliasing semantics (best-effort / no guarantees)

the implementation may alias bytes/string fields, makes no guarantees, and it’s always correct to ignore alias enabling.

That matches what I saw in practice.

I also understand (and will reflect in docs) that aliasing is generally only possible when parsing from a flat input. Stream backed decoding generally can’t safely alias because buffers are refilled/reused.

Additional concerns

To avoid surprises later during review, here are a few things I’m explicitly considering:

• Memory retention trade offs:
  I understand the historical String.substring() change you mentioned. The same risk exists with aliased ByteString/ByteBuffer slices. If a caller retains a small slice from a large request buffer, it can accidentally keep the entire large buffer alive, increasing heap pressure and GC.
  I’ll explicitly warn about this and recommend copying/interning into owned storage when values must be retained beyond parsing or when buffers are pooled.
• Pooled buffers / lifetime hazards:
  In high throughput ingestion systems, request buffers are often pooled. If aliasing is enabled and code stores returned ByteString values without copying, it can lead to subtle corruption when the buffer is reused. I’ll ensure docs call this out clearly.
• ByteBuffer safety:
  readByteBuffer() can return a ByteBuffer.slice() into an underlying array when aliasing is enabled in array backed decoders, and there’s a TODO in tree about making that buffer read only. Even without aliasing guarantees, the mutability/statefulness of ByteBuffer makes it easy for callers to accidentally mutate contents or misuse cursor state. This is an area I’d like guidance on before proposing any behavior changes.

Based on your feedback, I’d like to proceed in a this order:

1. Small PR: documentation clarifications only (Java runtime)
   Update CodedInputStream.enableAliasing(boolean) docs to explicitly describe:

   • best effort semantics (“may alias, no guarantees, ignoring is correct”),
   • flat input limitation,
   • buffer lifetime / pooled buffer hazards
   • and mention that readByteBuffer() may return a mutable view and should be treated carefully.

2. Docs only PR: long form “advanced parsing patterns” guide
   A separate doc that:

   • explains readTag loops, skipField, and pushLimit/popLimit
   • includes ASCII diagrams explaining cursor movement and why popLimit(oldLimit) is required
   • includes guidance on reading bytes first vs eager UTF-8 decoding (dedupe/intern patterns + validation gotchas)
   • includes a generic “telemetry style nested payload” case study (no OTLP/OpenTelemetry references).

   This doc would clearly state that generated parsing + overlay messages are the preferred approaches for most users, and the content is for advanced/internal style usage.

3. Safety PR read only ByteBuffer handling
   I’d like your preference here before investing:

   • Would you accept changing the aliasing fast path in readByteBuffer() to return asReadOnlyBuffer() (aligning with the TODO)?
   • Or would you prefer a new API method for read only buffers instead of changing existing behavior?

[esrauchg]

Your proposed PR1 sounds good.

PR2 I'm unsure about, you may want to consider publishing this somewhere yourself and then proposing that it be merged upstream to our documentation, or we could even consider linking to your documentation somewhere (as 'non-authoritative' since we couldn't vouch for you changing it later)

(Edited) Re: .asReadOnlyBuffer(), I'll need to check with the team to see if we think thats the intended semantic or not (note that e.g. readByteArray is there and can't be readonly here). Unfortunately if we did want to change it, we maybe would need to consider it a breaking change then we couldn't do it until 2027-Q1 at the earliest since we're not doing breaking changes in JavaProto until then. For the non-aliased case of that, it actually wouldn't be that crazy for someone to use this method and then modify the buffer afterwards.

So I think at least until 2027-Q1 the decision space on this one is effectively restricted to "document the behavior and recommend callers immediately do a asReadOnlyBuffer(), or do that same thing and also add in that we expect to change the behavior in a future breaking change release of JavaProto".

[samrod13]

@esrauchg Here's PR 1 #25247