fix(llc)!: prevent external mutation of ClientState collections

[xsahil03x]

Closes FLU-500

Summary

The collection getters on ClientState — channels, users, activeLiveLocations — returned live internal references. Callers could mutate the cache directly and silently bypass channelsStream / usersStream / activeLiveLocationsStream. Wrap them in unmodifiable maps/lists at write time so both the synchronous getter and the stream emit immutable values, and lock down the cache-mutation surface with @internal.

What changed

Read-side

• state.channels, state.users, state.activeLiveLocations now return unmodifiable maps/lists. Calling .clear(), .remove(...), [k] = v, etc. throws UnsupportedError.
• The wrap happens once at write time inside the setter / cache-mutation method, so the getter is zero-allocation. Subscribers to channelsStream / usersStream / activeLiveLocationsStream also receive unmodifiable values.
• Initial seeds are unmodifiable too — subscribers connecting before any write still see immutable values.

Write-side hardening

• All write calls in ClientState go through safeAdd(...) (the existing close-safe extension). Emissions after close are no-ops instead of throwing.
• removeChannel early-returns when the channel isn't cached and emits a freshly-built map, so .distinct() subscribers correctly observe the change. Previously channels = channels..remove(cid) re-emitted the same reference and missed the change for .distinct().
• dispose() closes _channelsController before iterating the cached channels and disposing them. Each Channel.dispose() calls removeChannel(cid) which safeAdd-no-ops on the closed controller, so teardown produces zero subscriber emissions (vs. N progressively-shrinking maps previously).

@internal audit
The cache-mutation API surface on ClientState is now marked @internal. App flows (connectUser, client.queryChannels, client.startLiveLocationSharing, etc.) populate the cache through these methods and are unaffected.

• Setters: channels=, currentUser=, activeLiveLocations=, totalUnreadCount=, blockedUserIds=
• Methods: updateUsers, updateUser, addChannels, removeChannel

ChannelClientState is left out of this PR — the same pattern can be applied later when threads/typing events become a priority.

Extracted wrapper module (post-review)

The unmodifiable-wrap discipline lives in two @internal wrapper classes (in lib/src/core/util/immutable_collection_subjects.dart):

• ImmutableMapBehaviorSubject<K, V>
• ImmutableListBehaviorSubject<E>

Both wrap a BehaviorSubject<UnmodifiableMapView/ListView>, extend StreamView<T>, and implement Sink<T> — so they behave like a regular broadcast stream + sink. Callers pass plain Map<K, V> / List<E> to add / safeAdd; the unmodifiable wrap happens inside, structurally impossible to forget or bypass via the wrapper's public surface.

The file also exports two public typedefs to keep the "Immutable" naming consistent:

• ImmutableMap<K, V> = UnmodifiableMapView<K, V>
• ImmutableList<E> = UnmodifiableListView<E>

The three collection controllers in ClientState now use the wrappers instead of the inline BehaviorSubject<...>.seeded(.unmodifiable(...)) pattern.

Tests

8 tests under ClientState mutation guards:

• state.channels returns an unmodifiable view
• state.users returns an unmodifiable view
• state.activeLiveLocations returns an unmodifiable view
• removeChannel emits a fresh map so .distinct() subscribers see the change
• initial seeded values are unmodifiable (before any write)
• channelsStream emits unmodifiable maps
• usersStream emits unmodifiable maps
• activeLiveLocationsStream emits unmodifiable lists

Plus 18 unit tests for the wrappers in immutable_collection_subjects_test.dart — covering both factory constructors, add/safeAdd wrap behavior, add throws after close, safeAdd no-op after close, subscribers receive unmodifiable values, and IS-A Stream/Sink.

Full LLC suite passes (1407/1407) on the rebased branch.

Breaking

fix(llc)! — code that was mutating these collections directly (state.channels.remove(...), state.users.clear(), etc.) will now throw UnsupportedError at runtime. Migration: go through the existing addChannels / removeChannel / updateUser / updateUsers methods (now @internal, but callable by SDK code; apps populate the cache via API methods that hit these internally).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e844af6-1d39-4ac6-ac2b-17ef3831980b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/unmodifiable-channels-map

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 87.71930% with 7 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v10.0.0@427609a). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/stream_chat/lib/src/client/client.dart	81.48%	5 Missing ⚠️
...b/src/core/util/immutable_collection_subjects.dart	93.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             v10.0.0    #2686   +/-   ##
==========================================
  Coverage           ?   67.02%           
==========================================
  Files              ?      408           
  Lines              ?    24394           
  Branches           ?        0           
==========================================
  Hits               ?    16349           
  Misses             ?     8045           
  Partials           ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.