spec: tolerate unknown enum values on the wire - #370
Draft
connor4312 wants to merge 1 commit into
Draft
Conversation
Adding a value to an existing string enum was documented as an additive, compatible change, but the Rust, Kotlin, and Swift clients failed the whole message when they decoded a value they didn't know. That made every future enum extension a breaking change in practice. Generate open string enums in all three clients: known values keep their existing named cases/constants, and unrecognized values are preserved verbatim so they round-trip unchanged. TypeScript and Go already tolerated arbitrary strings. Unknown values are now reachable in reducer code, so treat an unrecognized PendingMessageKind as a no-op instead of falling through to the queued-message path, and state the forward-compatibility rule in versioning.md for enum values, union variants, unknown object fields, and unknown error codes. Closes #366 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
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
Makes unrecognized string enum values decode, degrade, and round-trip instead of failing the whole message.
scripts/generate-{rust,kotlin,swift}.ts) now emit open string enums:Unknown(String), with hand-rolledSerialize/Deserializeandas_str().case unknown(String),RawRepresentableoverString.@JvmInline value classoverStringwith the known values as companion constants (TurnState.COMPLETEstill resolves).PendingMessageKindis now a no-op in every client. Previously the non-steeringbranch was an implicit "else = queued", which — once unknown values became decodable — would have written a future kind intoqueuedMessages. Rust also needed.clone()in a few spots since these enums are no longerCopy.docs/specification/versioning.md: spells out the ignore-unknown rule for enum values, discriminated-union variants, unknown object fields (including command params/results), and unknown error codes — not just actiontype.Why
Closes #366.
versioning.mdpromises additive changes are safe within a MAJOR, but adding a value to any existing discriminant enum was a hard decode failure on peers built against an earlier version. The forward-compat intent was already there for polymorphic unions (Unknown(serde_json::Value)) and bitsets (unknown bits preserved) — string enums were the gap. Worth fixing before 1.0, since after that every enum extension effectively becomes a MAJOR change.Notes for reviewers
PROTOCOL_VERSIONbump. The wire format is unchanged; this only changes how clients decode values they don't recognize.match/switchon these enums or relied onCopyin Rust — they'll now need an unknown arm. That's the point of the fix, but it's the thing to sanity-check.versioning.mdand covered by the existing017-unknown-wire-keys-ignoredfixture. Flagging it since it was raised as an open question rather than a given.Validation
npm run generate(no drift) andnpm testat the root;cargo test --workspace,./gradlew build(JDK 17 container),swift test,go test ./..., and the TypeScript client'snpm test && npm run build. Reducer branch coverage stays at 100%.Also reviewed by a council of three models; their one finding — the
PendingMessageKindfall-through above — is fixed and covered by the new reducer fixtures.