feat!: reenable WS fallback by szuperaz · Pull Request #1889 · GetStream/stream-chat-js

szuperaz · 2026-09-28T19:47:26Z

Breaking changes

transport.changed event renamed to connection.fallback_activated

https://linear.app/stream/issue/REACT-1181/reenable-ws-fallback

Reintroduce long-poll fallback if WS connection fails (and fallback is enabled).

How WS fallback works?

If WS fails to connect, and we're online, we try the WS fallback
Backend has a long-poll endpoint that we call, the sequence:
1. To create a connection, we send an auth message, and the backend sends back a connection_id
1. Once we have a connection id, we call again the long-poll endpoint with the id
3.1 If no new events are received, backend returns an empty response after 20secs, and we call the poll endpoint again
3.2 If we receive any event, backend immediately returns with the events, we dispatch the events, and call the poll endpoint again
If any error occurs that can be retired, we retry with the same connection id. Backend preserves the connection id for ~60-90s for us, so we reconnect with same connection id. If that id is gone, we get a clear error from backend, and do a full retry with new connection id and dispatch the connection.ok even if that was successful. If an error happens that can be retired, we set state to unhealthy, and wait for an "online" event to reconnect. Since the fallback sets the client.wsConnect.isHealthy flag, the recovery manager can kickstart a state recovery when necessary, so it should work the same way as it does for regular WS.

Implementation details

The main goal was to be as close to v9 as possible, Claude flagged a lot of potential bugs with ws fallback implementation, none of them is fixed on purpose to avoid unnecessary changes. Any change comes from adapting to v10's logic:

enableWSFallback -> moved to config service instead of ctr param
v9 used a 6s connection fallback when enableWSFallback: true, this is not there in v10, integrators can use the connectTimeoutMs param to lower the default 15secs if they want a shorter trial period
The fallback implementation sets isHealthy on the client.wsConnection class, just like on v9 the fallback took WS's place to report this
The WS fallback is only started if the network reporter reports we're online. Since the default reporter on Node and RN reports the WS status, we ignore the default reporter on those platforms and start fallback regardless of network status (v9 worked the same way). Since the RN SDK installs its own network reporter, we have accurate info in the RN SDK.

Changes on this branch that are not fallback related:

In StableWSConnection we abort an in-progress connection if disconnect was called while we were waiting on the token -> this potentially could've opened a WS connection after disconnect (in case of longpoll it would have meant receiving events on WS and long poll too).
disconnectUser will not reset tokenManager if a new connection was started while it waited for WS to close. This is a preexisting bug, nothing to do with this PR, but since Claude likes to report it anytime we have any WS-related change, it's fixed here finally.
ApiClient no longer waits for connectionId on requests where connection_id is part of the API request, but no watch/presence flag is set. This only affects stopWatching, connection id is now waited in client instead of ApiClient. Not a customer-facing change. The reason: for longPoll we have to be able to send the connection request without connection_id set.
ApiClient waits for in-progress tokens -> not related to this PR, but noticed while testing it, it seems waiting for the token wasn't ported, it doesn't cause issues when you wait for WS connection anyway, so that's why we missed it all this time (same in v9)

…ng after a token load Two gaps in StableWSConnection, both reachable through closeConnection() while the token provider is still loading: - _connect() never re-checked isDisconnected after awaiting the token, so a socket was still built after disconnect(). It carried the current wsID, so its callbacks were live and it published a connection id and events behind the close. - _reconnect() called _settleConnectPromises() even when _connect() returned early, resolving setUserPromise for a connection that was never made. That defeats connectUser's check that its own attempt is still the current one.

…d reset runs

Restores v9's WSConnectionFallback at src/connection_fallback.ts and the enableWSFallback client option, with v9's switching logic back in client.connect(). The class changes only where v10 removed what it relied on: it writes client.wsConnection.state instead of dispatching connection.changed, drives ConnectionIdManager, follows client.networkConnection instead of window events, polls /api/v2/longpoll, and sends connection_id in the URL so the request layer's connection-id gate does not hold its polls and close.

MartinCupela · 2026-09-30T08:11:59Z

+      // hosts without a network API mirrors the WebSocket, so its "offline" only means the socket
+      // is down, and is ignored.
+      const { networkConnection } = this.client;
+      const isDeviceOffline =


We actually cannot tell reliably if the device is offline if using custom reporter or the default WS reporter. In that case long-poll would be applied only in browsers and not RN (which relies on WS based reporter)?

We never rely on default WS reporter here, exactly because that is not reliable. We trust custom reporter, the reasoning for that is in the above comment.

But that means that the RN SDK will not use WSConnectionFallback unless custom reporter is provided. Is that correct?

No, if the default reporer is used in RN, we will fallback, exactly because we ignore the unreliable offline signal from the default reporter.

RN SDK itself installs a custom reporter, and fallback works with that one too.

MartinCupela · 2026-09-30T08:39:29Z

    })
  | { type: 'connection.recovered' }
+  // `enableWSFallback` switched from the WebSocket to long-polling.
+  | ({ type: 'transport.changed' } & { mode: string })


I think that 'connection.recovered' and 'transport.changed' belong to the same family / group of events meaning related to the WS connection (or just connection). I would probably namespace them the same way so that it is clear they belong together. Word 'transport' sounds ok, but could also be misleading if standing alone referring to any kind of transport protocol not related to maintaining the real-time connection.

This is the same name brought back from v9, I'm not really sure it makes the breaking change to rename it, but if you want to do this and have a name in mind, I can rename it

What about 'connection.fallback'. WDYT @szuperaz and @isekovanic ? Even though we are bringing something back, we have a unique opportunity to make it better.

We seem to be using verbs in the past tense here, so in the end used connection.fallback_activated

MartinCupela · 2026-09-30T08:56:42Z

+      const baseURL =
+        resolved === LONG_POLL_PATH
+          ? // replace port if present for testing with local API
+            this.client.baseURL?.replace(':3030', ':8900')


Why writing code for test purposes? Is there a purpose beyond fitting the test suite expectations?

We have the same thing for WS URL too: https://github.com/GetStream/stream-chat-js/blob/release-v10/src/client.ts#L516 - we need these swaps to run the SDK with a local backend. Both are existing concepts in master too.

Anyways looks smelly to hard-code this stuff. I think this belongs to the config service rather than hard-code some ports in the SDK code.

Yeah, we can do that, but then you have config params just for testing with local backend, because integrators would never need to set this. In any case, I don't think this PR is related. We can track it in Linear if we want to, but I don't think we should fix it here.

… of file

MartinCupela · 2026-09-30T14:36:37Z

+   *
+   * @internal
+   */
+  disconnect = async (timeout = 2000, connectionId?: string) => {


Do we need to pass the connectionId if we have access to the connectionIdManager? We already access the connectionIdManager here for example: https://github.com/GetStream/stream-chat-js/pull/1889/changes#diff-de6aeb8ccbca31560cf64bbc3f76666ba4dfbf4786de3368cda54d90987269f3R76

We pass because connection id is wiped as soon as disconnect starts. But we need the connection id to be able to send close request. WS doesn't have the same issue.

Since connection id is reset by client we make this connection explicit by providing this as a method param, instead of relying only on client calling the method after wsFallback doesn't need it anymore, which would be implicit.

…NetworkStatusReporter

szuperaz added 3 commits September 25, 2026 11:56

fix(client): keep the next user's token when disconnectUser's deferre…

96d8bbe

…d reset runs

szuperaz changed the title ~~Add back ws fallback~~ feat: reenable WS fallback Sep 28, 2026

szuperaz added 8 commits September 28, 2026 16:12

fix: review fixes

342a02f

refactor: move WSFallback connect to WSConnection

3f8a4d6

refactor: use generated longPoll endpoint

a5fbba1

fix: review fixes

54aa92b

fix: empty token fallback

e2f8d90

refactor: remove unnecessary comments

a937e3c

refactor: remove more comments

fc444ad

fix: wait for token in api client

f2d38f8

szuperaz marked this pull request as ready for review September 29, 2026 21:31

szuperaz requested review from MartinCupela, isekovanic, oliverlaz, santhoshvai and vishalnarkhede as code owners September 29, 2026 21:31

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/networkConnection/NetworkConnectionObserver.ts

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/WSConnectionFallback.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/client.ts Outdated

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnectionFallback.ts

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/WSConnection.ts

MartinCupela reviewed Sep 30, 2026

View reviewed changes

Comment thread src/client.ts Outdated

isekovanic requested changes Sep 30, 2026

View reviewed changes

Comment thread src/connection/wsConnection/StableWSConnection.ts Outdated

Comment thread src/connection/wsConnection/WSConnectionFallback.ts

szuperaz added 7 commits September 30, 2026 07:26

refactor: move WSFallback class to wsConnection folder

391cb41

refactor: rename ConnectionState to WSFallbackConnectionState

ef2196c

refactor: remove UR type

bd4dbc1

fix: mark methods as internal or private; move private methods to end…

f6e2d79

… of file

refactor: removed unused isHealthy getter

aa4560d

refactor: remove connectionID from WS fallback

6a75c58

refactor: reword misplaced comment

f0b8c3b

MartinCupela reviewed Sep 30, 2026

View reviewed changes

szuperaz added 4 commits September 30, 2026 09:57

fix: set local state before notifying subscribers

5e55432

fix: small fix

93b9957

refactor: rename isStatusDerivedFromSocket to usesDefaultWSConnection…

d14921e

…NetworkStatusReporter

feat!: rename transport.changed to connection.fallback_activated

7fbf7fc

szuperaz changed the title ~~feat: reenable WS fallback~~ feat!: reenable WS fallback Sep 30, 2026

szuperaz added 2 commits September 30, 2026 12:49

docs: add warning for enableWSFallback option

92e3035

fix: remove isDisconnect fix

9cc90c6

Conversation

szuperaz commented Sep 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Breaking changes

How WS fallback works?

Implementation details

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szuperaz Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szuperaz Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

szuperaz commented Sep 28, 2026 •

edited

Loading

szuperaz Sep 30, 2026 •

edited

Loading

szuperaz Sep 30, 2026 •

edited

Loading