Text chat 3: fluxer-proto expressions, threads and synced preferences (#253) #297

Manually merged
charles merged 4 commits from textchat-3-proto-expressions-threads-prefs into textchat 2026-11-12 14:21:08 +00:00
Owner

Stacked on: textchat-1-proto-message-content

What this builds

fluxer-proto gains the expression, thread and synced-preferences protocol of Text chat 3 (spec §3.1 "Threads", "Expressions", "GIFs", "Saved media", "Synced preferences"; §5 prefs):

  • Guild emoji and stickers (models::expressions): GuildEmoji { id, name, animated }, GuildSticker { id, name, description, tags, animated }. Guild.emojis is typed (was Vec<Value>), Guild.stickers is new, GuildReadyData.{emojis, stickers} are new; all lenient. GatewayEvent::{GuildEmojisUpdate, GuildStickersUpdate}.
  • Threads (models::thread): thread fields on Channel (thread_metadata, message_count, total_message_sent, member_count, own member; owner_id existed), ThreadMember, ThreadMuteConfig, ThreadListSync, ThreadMembersUpdate, requests ThreadCreateFromMessage and ThreadCreate. GuildReadyData.threads: Option<Vec<Channel>> keeps the key's presence (absent = threads off; present, null included, = on, as ThreadGuilds.ts:63). GatewayEvent::{ThreadCreate, ThreadUpdate, ThreadDelete, ThreadListSync, ThreadMemberUpdate, ThreadMembersUpdate}. MessageThread.member is now typed (Text chat 1 left it in IGNORED_FIELDS for this task).
  • GIFs (models::gif): Gif, GifMedia, GifFeatured, GifCategory; WellKnown.gif: Option<GifConfig>.
  • Saved media (models::meme): FavoriteMeme (every field of FavoriteMemeResponse), GatewayEvent::{FavoriteMemeCreate, FavoriteMemeUpdate, FavoriteMemeDelete}.
  • Synced preferences (prefs::{mod, wire, pickers}): SyncedPreferences::decode(&str) -> Result<Self, PrefsError> / encode(&self) -> String with emoji_picker, sticker_picker, memes_picker, skin_tone, favorite_gifs, soundboard_favorites (#92) and sanitize_urls, field numbers from preferences.proto / pickers.proto. The value keeps the decoded bytes; encode re-emits every top-level field whose value did not change byte for byte and in place, and rewrites only the changed ones (the same field-level merge the original does in SyncedPreferencesEngine.ts). Every parsed sub-message also keeps its unknown sub-fields. Hand-written protobuf (varint/LEN/I32/I64 only): no new crate. UserSettings::{synced_prefs(), sanitize_urls()}.
  • TYPED_DISPATCH_NAMES grows by 11 (47), UNTYPED_IN_FOUNDATION shrinks to 39.

How it was tested

  • tests/prefs.rs: decode reads every picker field of the golden snapshot; encode(decode(x)) == x; changing frecency rewrites field 20 only (every other top-level chunk identical, same order), and the unknown sub-field inside emoji_picker survives; each owned field changed alone touches only its field; unknown top-level fields 999 (from the fork's encoder) and 1000 (appended) survive a rewrite; "" is the default and encodes to ""; URL-safe unpadded input is accepted; malformed input is PrefsError; proptests over random bytes, random text and the fixture with a corrupted byte (no panic, and whatever decodes round-trips).
  • Golden fixture from the fork's own encoder: fixtures/prefs/synced_preferences.b64 was produced by running the fork's generated schema with its installed @bufbuild/protobuf 2.16.0 under Node 22, read-only, output written outside the fork; fixtures/prefs/README.md has the script and steps. It sets every top-level field of preferences.proto and two unknown fields.
  • tests/expressions.rs, tests/threads.rs: every new gateway fixture parses into its variant; old guild/READY fixtures still parse; READY threads absent vs present vs null; GIF featured/search, well-known gif, memes; lenient entries.
  • tests/models_roundtrip.rs: the six new REST fixtures round-trip strictly and tolerate unknown fields.
  • FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci green locally (Linux).

Fixtures are shaped from the server source; the fixture commit (8be8a3d) names file and line for each.

Deviations from the plan

  • ThreadCreate/ThreadUpdate/ThreadListSync/ThreadMemberUpdate/ThreadMembersUpdate/FavoriteMeme* variants hold a Box<…> (as ChannelCreate(Box<Channel>) already does) to keep GatewayEvent small; matching GatewayEvent::ThreadCreate(channel) works the same.
  • ThreadDelete.parent_id is Option<Snowflake> (lenient); the server always sends it.
  • Also added beyond the Interfaces block: Channel.{total_message_sent, member}, ThreadMember, ThreadMuteConfig, ThreadListSync.channel_ids, UserSettings::{synced_prefs, sanitize_urls} (spec §5 lists sanitize_urls as a UserSettings accessor; Text chat 2 owns synced_preferences() -> Option<&str>, so the decoded accessor is named synced_prefs to avoid a clash), SyncedPreferences::{from_bytes, to_bytes}, prefs::wire::fields (public so Text chat 14 can compare snapshots field by field), prefs::UnknownFields (an unknown field on each picker message: construct with ..Default::default()).
  • Files outside the list, kept minimal: models/instance.rs (WellKnown.gif, named by the Interfaces block), models/message.rs (MessageThread.member), lenient.rs (present_lenient_vec, lenient_map), Cargo.toml (base64.workspace = true: already a workspace dependency used by fluxer-api and fluxer-platform, so nothing new enters the graph or cargo deny), crates/fluxer-core/src/guilds.rs (one line: stickers: Vec::new() in a Guild literal), crates/fluxer-gateway/tests/{machine,connection}.rs and fixtures/gateway/unknown_event.json (they used FAVORITE_MEME_CREATE as the example of an untyped dispatch; it is typed now, so the example is WEBHOOKS_UPDATE, shaped from WebhookService.ts:642-647 plus the gateway's guild_id).
  • An extra fixture fixtures/gateway/thread_member_update.json (THREAD_MEMBER_UPDATE is a new typed event; the plan's list omits it).

For the reviewer

  • Review Focus 3: prefs/mod.rs to_bytes is the clobber guard; tests/prefs.rs prefs_changing_* are the proof.
  • The server accepts a synced_preferences_base_hash on PATCH /users/@me/settings (409 on mismatch, UserAccountSettingsService.ts:272-279); not modelled here, worth knowing for Text chat 2/14.

Closes #253

🤖 Generated with Claude Code

Stacked on: textchat-1-proto-message-content ## What this builds `fluxer-proto` gains the expression, thread and synced-preferences protocol of Text chat 3 (spec §3.1 "Threads", "Expressions", "GIFs", "Saved media", "Synced preferences"; §5 `prefs`): - **Guild emoji and stickers** (`models::expressions`): `GuildEmoji { id, name, animated }`, `GuildSticker { id, name, description, tags, animated }`. `Guild.emojis` is typed (was `Vec<Value>`), `Guild.stickers` is new, `GuildReadyData.{emojis, stickers}` are new; all lenient. `GatewayEvent::{GuildEmojisUpdate, GuildStickersUpdate}`. - **Threads** (`models::thread`): thread fields on `Channel` (`thread_metadata`, `message_count`, `total_message_sent`, `member_count`, own `member`; `owner_id` existed), `ThreadMember`, `ThreadMuteConfig`, `ThreadListSync`, `ThreadMembersUpdate`, requests `ThreadCreateFromMessage` and `ThreadCreate`. `GuildReadyData.threads: Option<Vec<Channel>>` keeps the key's presence (absent = threads off; present, `null` included, = on, as `ThreadGuilds.ts:63`). `GatewayEvent::{ThreadCreate, ThreadUpdate, ThreadDelete, ThreadListSync, ThreadMemberUpdate, ThreadMembersUpdate}`. `MessageThread.member` is now typed (Text chat 1 left it in `IGNORED_FIELDS` for this task). - **GIFs** (`models::gif`): `Gif`, `GifMedia`, `GifFeatured`, `GifCategory`; `WellKnown.gif: Option<GifConfig>`. - **Saved media** (`models::meme`): `FavoriteMeme` (every field of `FavoriteMemeResponse`), `GatewayEvent::{FavoriteMemeCreate, FavoriteMemeUpdate, FavoriteMemeDelete}`. - **Synced preferences** (`prefs::{mod, wire, pickers}`): `SyncedPreferences::decode(&str) -> Result<Self, PrefsError>` / `encode(&self) -> String` with `emoji_picker`, `sticker_picker`, `memes_picker`, `skin_tone`, `favorite_gifs`, `soundboard_favorites` (#92) and `sanitize_urls`, field numbers from `preferences.proto` / `pickers.proto`. The value keeps the decoded bytes; `encode` re-emits every top-level field whose value did not change byte for byte and in place, and rewrites only the changed ones (the same field-level merge the original does in `SyncedPreferencesEngine.ts`). Every parsed sub-message also keeps its unknown sub-fields. Hand-written protobuf (varint/LEN/I32/I64 only): no new crate. `UserSettings::{synced_prefs(), sanitize_urls()}`. - `TYPED_DISPATCH_NAMES` grows by 11 (47), `UNTYPED_IN_FOUNDATION` shrinks to 39. ## How it was tested - `tests/prefs.rs`: decode reads every picker field of the golden snapshot; `encode(decode(x)) == x`; changing frecency rewrites field 20 only (every other top-level chunk identical, same order), and the unknown sub-field inside `emoji_picker` survives; each owned field changed alone touches only its field; unknown top-level fields 999 (from the fork's encoder) and 1000 (appended) survive a rewrite; `""` is the default and encodes to `""`; URL-safe unpadded input is accepted; malformed input is `PrefsError`; proptests over random bytes, random text and the fixture with a corrupted byte (no panic, and whatever decodes round-trips). - **Golden fixture from the fork's own encoder**: `fixtures/prefs/synced_preferences.b64` was produced by running the fork's generated schema with its installed `@bufbuild/protobuf` 2.16.0 under Node 22, read-only, output written outside the fork; `fixtures/prefs/README.md` has the script and steps. It sets every top-level field of `preferences.proto` and two unknown fields. - `tests/expressions.rs`, `tests/threads.rs`: every new gateway fixture parses into its variant; old guild/READY fixtures still parse; READY `threads` absent vs present vs `null`; GIF featured/search, well-known `gif`, memes; lenient entries. - `tests/models_roundtrip.rs`: the six new REST fixtures round-trip strictly and tolerate unknown fields. - `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` green locally (Linux). Fixtures are shaped from the server source; the fixture commit (8be8a3d) names file and line for each. ## Deviations from the plan - `ThreadCreate`/`ThreadUpdate`/`ThreadListSync`/`ThreadMemberUpdate`/`ThreadMembersUpdate`/`FavoriteMeme*` variants hold a `Box<…>` (as `ChannelCreate(Box<Channel>)` already does) to keep `GatewayEvent` small; matching `GatewayEvent::ThreadCreate(channel)` works the same. - `ThreadDelete.parent_id` is `Option<Snowflake>` (lenient); the server always sends it. - Also added beyond the Interfaces block: `Channel.{total_message_sent, member}`, `ThreadMember`, `ThreadMuteConfig`, `ThreadListSync.channel_ids`, `UserSettings::{synced_prefs, sanitize_urls}` (spec §5 lists `sanitize_urls` as a `UserSettings` accessor; Text chat 2 owns `synced_preferences() -> Option<&str>`, so the decoded accessor is named `synced_prefs` to avoid a clash), `SyncedPreferences::{from_bytes, to_bytes}`, `prefs::wire::fields` (public so Text chat 14 can compare snapshots field by field), `prefs::UnknownFields` (an `unknown` field on each picker message: construct with `..Default::default()`). - Files outside the list, kept minimal: `models/instance.rs` (`WellKnown.gif`, named by the Interfaces block), `models/message.rs` (`MessageThread.member`), `lenient.rs` (`present_lenient_vec`, `lenient_map`), `Cargo.toml` (`base64.workspace = true`: already a workspace dependency used by fluxer-api and fluxer-platform, so nothing new enters the graph or `cargo deny`), `crates/fluxer-core/src/guilds.rs` (one line: `stickers: Vec::new()` in a `Guild` literal), `crates/fluxer-gateway/tests/{machine,connection}.rs` and `fixtures/gateway/unknown_event.json` (they used `FAVORITE_MEME_CREATE` as the example of an untyped dispatch; it is typed now, so the example is `WEBHOOKS_UPDATE`, shaped from `WebhookService.ts:642-647` plus the gateway's `guild_id`). - An extra fixture `fixtures/gateway/thread_member_update.json` (THREAD_MEMBER_UPDATE is a new typed event; the plan's list omits it). ## For the reviewer - Review Focus 3: `prefs/mod.rs` `to_bytes` is the clobber guard; `tests/prefs.rs` `prefs_changing_*` are the proof. - The server accepts a `synced_preferences_base_hash` on `PATCH /users/@me/settings` (409 on mismatch, `UserAccountSettingsService.ts:272-279`); not modelled here, worth knowing for Text chat 2/14. Closes #253 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Failing tests for Text chat 3 (expressions.rs, threads.rs, prefs.rs) and the fixtures
they read, each shaped from the fork at ba98441b4:

- gateway/guild_emojis_update.json, guild_stickers_update.json:
  fluxer_api/src/api/guild/services/content/EmojiService.ts:301-307 and
  StickerService.ts:342-348 ({emojis}/{stickers} via mapGuildEmojiToResponse /
  mapGuildStickerToResponse, guild/GuildModel.ts:98-118), guild_id added by
  fluxer_gateway/src/guild/guild_dispatch.erl:91.
- gateway/thread_create.json, thread_update.json, thread_delete.json,
  thread_members_update.json, thread_member_update.json:
  fluxer_api/src/api/channel/services/thread/ThreadDispatch.ts:26-93 (thread object from
  ThreadMappers.ts:42-92); the internal _fluxer_* keys are stripped by
  guild_dispatch.erl:131-136 / guild_thread_payload.erl:139-146.
- gateway/thread_list_sync.json: fluxer_gateway/src/guild/guild_thread_view.erl:100-123.
- gateway/favorite_meme_create.json, favorite_meme_delete.json:
  fluxer_api/src/api/favorite_meme/FavoriteMemeService.ts:213-218, 454-458 and
  FavoriteMemeModel.ts:9-32.
- gateway/user_settings_update_prefs.json:
  fluxer_api/src/api/user/services/UserAccountUpdatePropagator.ts:17-23,
  user/UserMappers.ts:296-375.
- rest/guild_emojis.json, guild_stickers.json: GuildEmojiController.ts:111-133
  (GuildEmojiWithUserResponse, packages/schema/src/domains/guild/GuildEmojiSchemas.ts:9-39).
- rest/gifs_featured.json, gifs_search.json: packages/schema/src/domains/gif/GifSchemas.ts:36-88,
  fluxer_gifs/src/types.rs:70-100 (placeholder left out when absent).
- rest/memes.json: FavoriteMemeModel.ts:9-32 (nullable fields written as null).
- rest/thread_created.json: ThreadController.ts:134-169 (201 ThreadChannelResponse),
  ThreadMappers.ts:19-41 (own member: muted, mute_config null), 58-92.
- prefs/synced_preferences.b64: encoded by the fork's own protobuf-es encoder
  (packages/schema/src/gen/fluxer/user/preferences/v1/*_pb.ts,
  packages/schema/src/domains/user/SyncedPreferencesCodec.ts), run read-only; how is in
  fixtures/prefs/README.md.

Refs #253

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Typed guild emoji and stickers (REST, READY/GUILD_CREATE, GUILD_EMOJIS_UPDATE,
GUILD_STICKERS_UPDATE), thread channels, members and dispatches with the READY
`threads` key presence kept, thread-create requests, GIFs and the well-known gif
config, saved media and FAVORITE_MEME_*, and `prefs::SyncedPreferences`: a
field-preserving protobuf codec for user_settings.synced_preferences that rewrites
only changed top-level fields and keeps unknown fields byte for byte.

The unknown-dispatch example in fluxer-gateway's tests and fixtures/gateway/
unknown_event.json moves from FAVORITE_MEME_CREATE (now typed) to WEBHOOKS_UPDATE,
shaped from fluxer_api/src/api/webhook/WebhookService.ts:642-647 plus the guild_id
the gateway adds (guild_dispatch.erl:91).

Refs #253

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Author
Owner

Independent review: Text chat 3 (diff 6e2d2389..776fc2e)

Tests named in the plan: all 12 are there. The prefs tests assert against the fork-encoded golden fixture: the exact picker values, the byte-identical round trip, and that changing a field rewrites only that field (checked for each of 20–26 and 82). Unknown top-level fields 999 and 1000 and unknown field 9 inside emoji_picker survive. Defaults are left out. There is a proptest over random bytes and over the fixture with one byte flipped.
Interfaces: every name in the Task 3 Interfaces block exists. Field numbers match preferences.proto and pickers.proto at ba98441b4.
Invariants: fluxer-core changed by one line only (stickers: Vec::new()). No new crate: base64 was already a workspace dependency. Each fixture's shape matches the server file and line its commit names (ThreadDispatch.ts, ThreadSchemas.ts, FavoriteMemeModel.ts and FavoriteMemeService.ts checked by hand). Fixtures contain no real secrets or signed URLs (*.example.invalid, ex=0&is=0&hm=0). Bad input returns Err and never panics. Bad list entries are dropped one at a time.
Review Focus 3: met. to_bytes compares each owned field's re-encoding before and after. Unchanged fields are copied from raw as they were. A changed field is written where it first appeared, and repeated occurrences of it are merged. Unknown fields at every depth are kept.
Local gate: FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci is green in the review worktree (exit 0, first run).

Findings

  • minor: ThreadCreate, ThreadUpdate, ThreadListSync, ThreadMember(s)Update and FavoriteMeme* are Box<..>, but the Interfaces block shows them unboxed. Consumers (Text chat 10, 14, 18) must deref them. This is not a break, but those tasks should know about it.
  • minor: UserSettings::synced_prefs() returns the empty snapshot when synced_preferences is present but not a string. A writer in Text chat 14 could then PATCH a fresh snapshot over the stored one. The server only ever sends a string or null, so this is low risk. Text chat 14 should still send synced_preferences_base_hash (409 on mismatch) as the implementer noted.
  • minor: FAVORITE_MEME_UPDATE has no fixture of its own. The test reuses the create payload, which is the same object on the server (FavoriteMemeService.ts:434-439).

Verdict: approve. No blocking findings, and local CI is green.

## Independent review: Text chat 3 (diff 6e2d2389..776fc2e) **Tests named in the plan:** all 12 are there. The prefs tests assert against the fork-encoded golden fixture: the exact picker values, the byte-identical round trip, and that changing a field rewrites only that field (checked for each of 20–26 and 82). Unknown top-level fields 999 and 1000 and unknown field 9 inside `emoji_picker` survive. Defaults are left out. There is a proptest over random bytes and over the fixture with one byte flipped. **Interfaces:** every name in the Task 3 Interfaces block exists. Field numbers match `preferences.proto` and `pickers.proto` at ba98441b4. **Invariants:** fluxer-core changed by one line only (`stickers: Vec::new()`). No new crate: `base64` was already a workspace dependency. Each fixture's shape matches the server file and line its commit names (ThreadDispatch.ts, ThreadSchemas.ts, FavoriteMemeModel.ts and FavoriteMemeService.ts checked by hand). Fixtures contain no real secrets or signed URLs (`*.example.invalid`, `ex=0&is=0&hm=0`). Bad input returns `Err` and never panics. Bad list entries are dropped one at a time. **Review Focus 3:** met. `to_bytes` compares each owned field's re-encoding before and after. Unchanged fields are copied from `raw` as they were. A changed field is written where it first appeared, and repeated occurrences of it are merged. Unknown fields at every depth are kept. **Local gate:** `FLUXER_SCREENSHOT_TESTS=1 cargo xtask ci` is green in the review worktree (exit 0, first run). ### Findings - **minor**: `ThreadCreate`, `ThreadUpdate`, `ThreadListSync`, `ThreadMember(s)Update` and `FavoriteMeme*` are `Box<..>`, but the Interfaces block shows them unboxed. Consumers (Text chat 10, 14, 18) must deref them. This is not a break, but those tasks should know about it. - **minor**: `UserSettings::synced_prefs()` returns the empty snapshot when `synced_preferences` is present but not a string. A writer in Text chat 14 could then PATCH a fresh snapshot over the stored one. The server only ever sends a string or `null`, so this is low risk. Text chat 14 should still send `synced_preferences_base_hash` (409 on mismatch) as the implementer noted. - **minor**: `FAVORITE_MEME_UPDATE` has no fixture of its own. The test reuses the create payload, which is the same object on the server (FavoriteMemeService.ts:434-439). **Verdict: approve.** No blocking findings, and local CI is green.
Refs #253

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
charles manually merged commit 3814156446 into textchat 2026-11-12 14:21:08 +00:00
Sign in to join this conversation.
No description provided.