Connection

A chat connection can fail in two ways. The device can lose its network, or the client's WebSocket can drop while the network is fine: the server closed it, the token expired, or a health check timed out. The client reports the two separately, so an app can tell "you're offline" from "reconnecting".

When the socket comes back, the client brings what the user is looking at up to date by itself, then announces it with connection.recovered.

On this page, a reconnect is the client's WebSocket opening again after it dropped: when the network comes back, when the device wakes from sleep, when the client reopens a socket the server closed, or after client.closeConnection() and client.openConnection(). The client's first connection isn't a reconnect.

This page covers both: the connection status, then recovery. Showing a lost-connection banner is on Connection status, and reading these stores in components on Reading state in components.

Connection status

The two stores can disagree either way. A socket can drop on a working network. And when the device loses its network, the socket can look healthy for up to 35 seconds, until its next health check fails, unless something tells the client about the loss. In a browser, the client learns it at once from the browser's offline event and marks the socket down. Elsewhere you install a network status reporter, as Device network explains.

No event announces when the socket goes up or down, or when the device goes online or offline. To follow them, subscribe to client.wsConnection.state for the socket, or client.networkConnection.state for the network.

Socket health

client.wsConnection.state holds { isHealthy, lastHealthyAt, lastUnhealthyAt }. isHealthy is always a boolean, so !isHealthy is safe. client.wsConnection.isHealthy reads the current value.

The store records every change, including a deliberate client.closeConnection(), and it records a drop the moment it happens. Most drops recover in under a second, so a UI that shows every drop at once makes a working app look broken. Wait offlineNotificationDisplayDelayMs before showing one, and cancel the wait if the socket comes back:

const delayMs = client.wsConnection.config.offlineNotificationDisplayDelayMs;
let timer: ReturnType<typeof setTimeout> | undefined;

const unsubscribe = client.wsConnection.state.subscribeWithSelector(
  ({ isHealthy }) => ({ isHealthy }),
  ({ isHealthy }) => {
    clearTimeout(timer);
    if (isHealthy) {
      console.log("Connected");
      return;
    }
    timer = setTimeout(() => console.log("Reconnecting…"), delayMs);
  },
);

The socket's timings are set through client.config, which Configuration explains:

client.config.set({
  client: {
    wsConnection: {
      connectTimeoutMs: 15_000, // how long connecting waits for the server
      healthCheckGracePeriodMs: 10_000, // extra time before a silent socket counts as dead
      offlineNotificationDisplayDelayMs: 5_000, // How long a UI should wait before showing a drop
      pingIntervalMs: 25_000, // how often a health check goes out
    },
  },
});

The values above are the defaults. client.wsConnection takes these options:

A timing value outside its bounds is moved to the nearest bound, and the client logs a warning.

Device network

client.networkConnection.state holds { isOnline, lastOnlineAt, lastOfflineAt }, and client.networkConnection.isOnline reads the current value.

isOnline is undefined when the status is unknown: nothing has reported it yet. Test it with === false:

if (client.networkConnection.isOnline === false) {
  // The device is offline.
}

// Wrong: also true while the status is unknown, such as before the first connection.
if (!client.networkConnection.isOnline) {
  // ...
}

The client can't detect the network by itself: every platform reports it differently. So a reporter tells it. A reporter is a function that reports the current status, reports again on every change, and returns a function that stops it.

In a browser, the client installs a reporter for you, based on navigator.onLine and the online and offline events. Install your own when you know the network status better than the browser does, for example from a host app that embeds the chat in a web view. Outside a browser, until a reporter is installed, the network status is inferred from the socket's connection state, which can't tell a dead socket from a lost network.

import type { NetworkStatusReporter } from "stream-chat";

const reporter: NetworkStatusReporter = (onStatusChange) => {
  // Report the current status right away, then on every change.
  onStatusChange(navigator.onLine);

  const handle = () => onStatusChange(navigator.onLine);
  window.addEventListener("online", handle);
  window.addEventListener("offline", handle);

  return () => {
    window.removeEventListener("online", handle);
    window.removeEventListener("offline", handle);
  };
};

client.config.set({
  client: { networkConnection: { statusReporter: reporter } },
});
// or, with the same effect:
client.networkConnection.setStatusReporter(reporter);

client.networkConnection takes this option:

The client uses the reporter installed last: a setStatusReporter() call replaces a reporter from client.config, and setting statusReporter in client.config replaces one from setStatusReporter(). A client.config.set() call that doesn't set statusReporter keeps the installed reporter. Installing the same function again does nothing, and client.networkConnection.setStatusReporter(null) removes the reporter and keeps the last status.

If the reporter throws while the client installs it, the client logs an error and installs nothing in its place, so isOnline stops changing. A host with no event to listen to can report the status directly with client.networkConnection.setStatus(isOnline).

Don't wait for isOnline to be true before sending requests. Requests don't depend on it, and they work while it's undefined. A reporter only makes the client faster: it notices a lost network before the socket's health check fails, and reconnects as soon as the network comes back instead of waiting for its next retry.

Connection recovery

What reloads after a reconnect

After that event, the thread list loads again, if it was opened in this session.

A first connection isn't a reconnect, so none of this runs then. <Channel/> activates the channel it shows, so that channel reloads. <Thread/> doesn't activate its thread. A thread reloads only while something holds it active, such as useActiveThread, which the app calls for the thread it shows. Otherwise it's marked stale and loads again when it's opened. Entity lifecycle explains Channel.activate() and Thread.activate().

Channels re-watched on demand

A watch is what makes the server send a channel's events to this client. The server ties watches to the connection, so a reconnect ends them all. The recovery steps watch again the channels each paginator loaded again, and the active channels.

The other channels the client holds aren't watched again. Their watchStatus in channel.state stays wasWatching. These include channels beyond the first 150 a paginator had loaded, channels opened earlier that aren't active, and channels no paginator holds. Watching them all again could exceed the server's watch limit. Instead, each one is watched again when the channel manager routes it after an event, for example notification.message_new when someone writes in it.

Event connection.recovered

connection.recovered fires after every reconnect: an automatic one, and client.closeConnection() followed by client.openConnection(). It doesn't fire on the first connection.

While recovery is on, the client has reloaded its active channels and threads by the time it fires, and its channel paginators are refreshing. Listen for it to refresh what the client doesn't own: results of one-off queries, counters, your own data.

For example, an app that shows the user's total unread count from a one-off query loads it again:

let totalUnread = 0;

const loadTotalUnread = async () => {
  const { total_unread_count } = await client.unreadCounts();
  totalUnread = total_unread_count;
};

const { unsubscribe } = client.on("connection.recovered", () => {
  void loadTotalUnread();
});

If the socket drops again while the client reloads, the event waits for the next reconnect, whose recovery fires it.

Turning recovery off or running it by hand

Turn recovery off when your app refreshes its data itself. The setting is read at each reconnect, so a change applies from the next one:

client.config.set({ client: { connectionRecovery: { enabled: false } } });

With recovery off, a reconnect refreshes nothing, and nothing is watched again:

So refresh what the user sees in a connection.recovered listener:

Channel.reload() and Thread.reload() reject when the request fails, so catch the error in your listener.

To run the SDK's recovery yourself, with recovery on or off, call client.connectionRecovery.recover(). It does the steps in What reloads after a reconnect:

• It fires connection.recovered once the active channels and threads have reloaded. The channel paginators can finish later.
• It holds the event back if the socket dropped while it ran, or is down when it finishes.
• It does nothing while the active channels and threads are still reloading.
• Don't call it from a connection.recovered listener. It fires the event itself, so the listener would call it again and again.

Used in

• Connection status
• Notifications UI
• System notification banner