Add try_encode_bounded: budget-checked single-pass encode entry points

[rsd-darshan]

Summary

Writers behind a transport or storage size cap (RPC frame limit, message-queue
cap, storage row limit) previously had to call try_encoded_len then encode
to guard a caller budget before encoding — two full tree walks over the message.
The SizeCache already holds everything write_to needs after compute_size,
but no public entry point exploited this.

• Message::try_encode_bounded(max_bytes, buf) — single size pass, budget
  check before write_to; nothing written on Err; returns encoded body
  length on Ok
• Message::try_encode_bounded_with_cache — same, caller-supplied cache
• ViewEncode::try_encode_bounded / try_encode_bounded_with_cache — view
  equivalents
• SizeCachePool::try_encode_bounded / try_encode_view_bounded — pooled
  equivalents (spill buffer returned to pool on both Ok and Err)
• EncodeError::ExceedsBudget { len, max_bytes } — new variant carrying
  the exact encoded size and the exceeded budget; distinct from
  MessageTooLarge (> 2 GiB), which takes precedence when both limits
  are exceeded

Test plan

• try_encode_bounded_within_budget_encodes_and_returns_len — within budget, output matches plain encode
• try_encode_bounded_at_exact_limit_succeeds — budget == encoded_len succeeds
• try_encode_bounded_over_budget_errors_and_writes_nothing — one byte under, Err, empty buffer
• try_encode_bounded_zero_budget_with_empty_message_succeeds — zero-length message + zero budget
• try_encode_bounded_over_protobuf_limit_errors_as_too_large — over 2 GiB → MessageTooLarge
• Pool variants: within budget, over budget (buffer returned and reusable), over protobuf limit
• All four shape above replicated on ViewEncode side (view::tests::view_try_encode_bounded_*, pool_try_encode_view_bounded_*)

Closes #283.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[iainmcgin]

[claude code] Approving. This is a clean implementation of #283 and the risky part is right.

The thing I most wanted to check is the invariant the optimization rests on. Collapsing two size passes into one means write_to consumes the SizeCache that compute_size populated, in the same order — and a desync there corrupts wire output silently, with wrong lengths and no panic, which a round-trip test on a small message would not necessarily catch. It holds: try_encode_bounded_with_cache is the same clear → compute_size → write_to shape as the existing try_encode_with_cache, with only a local len read and an early return between the passes. Nothing touches the cache.

Also verified: checked_encode_size(...)? runs first, so MessageTooLarge correctly wins over ExceedsBudget; a max_bytes above the protobuf limit is simply never the binding constraint (no clamp needed); max_bytes == 0 on an empty message succeeds as you documented; the pool variants release(cache) unconditionally, so the spill buffer returns on both paths, and your ..._returned tests prove it by encoding again afterwards; and there is not a single as usize/as u32 cast in the implementation, so nothing truncates on the 32-bit target CI builds.

Pushed one commit (597091c):

An append-semantics test. Your doc promises "nothing reaches buf on Err", but every test starts from an empty Vec, so the case where it matters most was unpinned: a caller framing several messages into one buffer, where a partial write corrupts the preceding message rather than leaving an obviously empty buffer. The new test pre-fills the sink, triggers ExceedsBudget, and requires the buffer to be byte-identical afterwards. It is load-bearing — moving write_to ahead of the budget check fails it (along with two of yours).

Changelog: it said "All four return the encoded body length" but six do, and the *_with_cache forms were introduced twice. Reworded.

Formatting: the pool.try_encode_view_bounded(...) call in the view test needed cargo fmt; CI's fmt check would have rejected it as it stood. Nothing to do with your logic — worth running cargo fmt --all before pushing next time and it'd never surface.

Two things I deliberately left alone, noted so they read as decisions rather than oversights: the bounded path doesn't call debug_assert_two_pass, which is consistent with the existing try_encode/try_encode_with_cache (a generic EncodeSink has no cheap written-byte count); and there's no try_encode_bounded_to_vec/_to_bytes convenience, a mild asymmetry with encode_to_vec that the sink form covers. The latter is a reasonable follow-up if callers ask.

Nice work — the PR body's claims all checked out against the code, which made this a verification rather than an investigation.

[iainmcgin]

[claude code] Re-approving: the push of 597091c (append-semantics test + changelog wording + fmt) dismissed the prior approval under the stale-review rule. All checks green on the updated head; the review above stands.