docs(schema): warn against in-place mutation of shared stream elements#1074
Open
hi-pender wants to merge 1 commit into
Open
docs(schema): warn against in-place mutation of shared stream elements#1074hi-pender wants to merge 1 commit into
hi-pender wants to merge 1 commit into
Conversation
StreamReader.Copy duplicates readers, not elements, so pointer elements (e.g. *Message) are shared across fan-out branches and may be consumed concurrently. In-place writes to map fields such as Message.Extra cause concurrent map read/write panics. Add GoDoc guidance at the places users are most likely to hit this: - StreamReader.Copy: copies share elements; treat them as read-only - StreamReaderWithConvert: convert must not modify its input in place - Message.Extra / AgenticMessage.Extra: copy-on-write instructions - adk WrapModel: stream-transform wrappers must return copies Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## alpha/10 #1074 +/- ##
===========================================
Coverage ? 83.07%
===========================================
Files ? 172
Lines ? 28228
Branches ? 0
===========================================
Hits ? 23449
Misses ? 3222
Partials ? 1557 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Adds GoDoc warnings about a recurring concurrency pitfall:
StreamReader.Copyfan-out duplicates readers, not elements, so pointer elements (e.g.*schema.Message) are shared across branches and may be consumed concurrently. Mutating a received message in place — especially map fields likemsg.Extra[k] = v— causesconcurrent map read/writepanics.Comment-only change; no behavior change.
Where the guidance was added
schema/stream.go—StreamReader.Copy: copies share the same element values; treat received elements as read-only, use copy-on-write to modifyschema/stream.go—StreamReaderWithConvert: the convert callback must not modify its input in place; return a new value (shallow-copy + clone changed map/slice fields)schema/message.go—Message.Extra: never write to Extra on a message you did not create; copy-on-write stepsschema/agentic_message.go—AgenticMessage.Extra: same guidanceadk/handler.go—TypedChatModelAgentMiddleware.WrapModel: wrappers transforming the response stream must shallow-copy + clone instead of writing in placeWhy
Users writing stream convert callbacks or ADK middleware commonly attach metadata via
msg.Extra[k] = von messages received from streams, which intermittently panics under fan-out. The doc comments now steer users to the copy-on-write pattern at every place they're likely to look.🤖 Generated with Claude Code