[6/6] api: Audit enums to handle unknown values where appropriate - #2395
Open
sm-sayedi wants to merge 61 commits into
Open
[6/6] api: Audit enums to handle unknown values where appropriate#2395sm-sayedi wants to merge 61 commits into
sm-sayedi wants to merge 61 commits into
Conversation
We'll soon change Message.type to use MessageType instead of String. This will make it compatible with the modern values "channel" and "direct" when the server starts sending them in the future. Having it next to Message seems more appropriate than its previous location.
…omJson And change MessageTypeConverter.fromJson to forward to MessageType.fromJson. In future commits, we can use the compatibility logic independent of MessageTypeConverter; simply by using MessageType.fromJson.
As of 2026-06, the server only sends "stream" type we already support. This change is for accepting the modern "channel" type that the server may start sending in the future.
This way, it can also accept "channel" and "direct" as the valid values for the message type when the server starts sending them in the future. As of 2026-06, the server only sends "stream" and "private" for message types. Now, we map them to "channel" and "direct" in deserialization.
The modern type "channel" was added in server-9 (FL-248).
`realm_wildcard_mention_policy` is deprecated in server-10 (FL-352), so making it optional will avoid throwing when the server stops sending it.
We were already handling unrecognized setting names in UserSettingsUpdateEvent by making the corresponding field nullable. To follow our usual pattern for handling unknown values from the Zulip server API, added an "unknown" value to UserSettingName and made the field non-nullable.
To make its name consistent with SubscriptionProperty.
We were already handling unrecognized property names in ChannelUpdateEvent by making the corresponding field nullable. To follow our usual pattern for handling unknown values from the Zulip server API, added an "unknown" value to ChannelProperty and made the field non-nullable.
And add dartdoc. Although the previous name (fromApiValue) was technically correct, we generally use that name when the API value differs from the serialized enum value generated by JsonEnum.fieldRename; for example, in SystemGroupName: 'role:administrators' -> SystemGroupName.administrators The new name (fromRawString) is generally used when the API value and serialized enum value are the same: 'allow_empty_topic' -> ChannelTopicsPolicy.allowEmptyTopic
To match the fallback value in UserTopicItem.visibilityPolicy and avoid throwing on unrecognized API values.
For use from other files.
To match the fallback behavior of Message.flags and avoid throwing on unrecognized API values.
And add dartdoc. Although the previous name (fromApiValue) was technically correct, we generally use that name when the API value differs from the serialized enum value generated by JsonEnum.fieldRename; for example, in SystemGroupName: 'role:administrators' -> SystemGroupName.administrators The new name (fromRawString) is generally used when the API value and serialized enum value are the same: 'unicode_emoji' -> ReactionType.unicodeEmoji
Previously, it would throw and the defined "unknown" value was never actually used. The purpose of having an "unknown" value is to handle unrecognized inputs without throwing.
sm-sayedi
force-pushed
the
1982-parse-enums-laxly-p6
branch
from
July 27, 2026 20:48
1c51e7a to
348e480
Compare
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.
Fixes #1982.
Rebased atop #2394.
Goes through all the enums defined in
lib/api(from top to bottom, both through the files and inside the files). Makes the enums accept unknown values or explains why we don't/can't accept them. For finding enum definitions inside a file, I usedenum [^{]+\{regex in VSCode "Find" feature (Cmd+Fshortcut).I have also taken the opportunity of going through all the API enums to use dot shorthands in their usages. To find all the usages of
FooEnum, I used\bFooEnum(\.\w+)regex in the VSCode "Search: Find in Files" feature (Shift+Cmd+Fshortcut) with case-sensitivity on and used the capture group ($1) as the replacement.