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.
• BehaviorSubject seeds are unmodifiable too — subscribers connecting before any write still see immutable values.

Write-side hardening

• All BehaviorSubject.add(...) calls in ClientState switched to 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.

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

Full LLC suite passes (1389/1389) 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: 37187cfa-ea80-40cf-9af4-7d91eecbec78

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 81.48148% with 5 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 ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             v10.0.0    #2686   +/-   ##
==========================================
  Coverage           ?   66.98%           
==========================================
  Files              ?      407           
  Lines              ?    24364           
  Branches           ?        0           
==========================================
  Hits               ?    16321           
  Misses             ?     8043           
  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.