Определение сетевого статуса

Сетевой статус в TanStack Query определяет текущее состояние подключения клиента к сети и напрямую влияет на поведение запросов: выполнение, повторные попытки, отложенные мутации и автоматические рефетчи. Библиотека рассматривает сетевой статус не как вспомогательную метрику, а как фундаментальный сигнал, от которого зависят стратегии доставки и синхронизации данных.

В основе лежит абстракция, позволяющая разделить работу с данными на два режима: когда сеть доступна и когда она недоступна. Это разделение критично для корректного управления кэшем, предотвращения лишних запросов и обеспечения предсказуемого поведения приложения при потере соединения.

Источники определения сетевого статуса

TanStack Query использует несколько уровней определения онлайн-состояния:

Основной источник информации о сети — встроенное браузерное свойство:

navigator.onLine

Это значение:

  • true — браузер считает себя подключенным
  • false — браузер считает соединение отсутствующим

Однако это значение не гарантирует фактическую доступность сервера. Оно отражает лишь наличие сетевого интерфейса или системного подключения, поэтому рассматривается как эвристика, а не строгая истина.

OnlineManager как централизованный контроллер

TanStack Query инкапсулирует логику сетевого статуса в onlineManager. Он отвечает за:

  • хранение текущего состояния сети
  • подписку на системные события
  • уведомление всех подписчиков библиотеки
  • управление переходами online/offline

Базовая реализация опирается на события браузера:

window.addEventListener('online', handler)
window.addEventListener('offline', handler)

При срабатывании этих событий состояние синхронизируется с navigator.onLine, после чего происходит уведомление всех активных query и mutation процессов.

Подписка на изменения сети

Система подписки реализована через реактивную модель: любые изменения сетевого статуса транслируются в QueryCache и QueryObserver.

Основные сценарии реакции:

  • повторная отправка запросов при восстановлении сети
  • активация отложенных мутаций
  • снятие блокировки retry-логики
  • запуск refetch для устаревших данных

Внутренне это реализуется через механизм listeners:

onlineManager.subscribe(() => {
  queryClient.resumePausedMutations()
  queryClient.refetchQueries({
    type: 'active',
    stale: true,
  })
})

Поведение запросов при смене статуса сети

Переход в offline

При потере соединения TanStack Query:

  • останавливает автоматические retry
  • переводит мутации в paused состояние (если включено)
  • предотвращает ненужные сетевые обращения
  • сохраняет состояние кэша без изменений

Важно, что кэш продолжает оставаться доступным, и чтение данных не блокируется.

Переход в online

При восстановлении сети:

  • выполняется retry для ожидающих мутаций
  • запускаются refetch-запросы для устаревших данных
  • активируются отложенные запросы
  • обновляется статус всех observers

Этот механизм делает систему самовосстанавливающейся без необходимости ручного вмешательства.

refetchOnReconnect и автоматическая синхронизация

Одним из ключевых параметров, связанных с сетевым статусом, является:

refetchOnReconnect

Он определяет поведение при восстановлении соединения:

  • true — автоматический рефетч активных запросов
  • false — сохранение текущего состояния без обновления
  • always — принудительное обновление независимо от stale-состояния

Пример конфигурации:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      refetchOnReconnect: true,
    },
  },
})

retry-логика и зависимость от сети

Retry механика тесно связана с сетевым статусом. При offline-состоянии TanStack Query может:

  • приостанавливать повторные попытки
  • откладывать retry до восстановления сети
  • учитывать exponential backoff только при наличии подключения

Базовая логика выглядит как комбинация:

  • наличие сети
  • количество попыток
  • стратегия повторов
retry: (failureCount, error) => {
  if (!navigator.onLine) return false
  return failureCount < 3
}

focusManager и косвенное влияние на сетевой статус

Хотя focusManager напрямую не управляет сетью, он часто работает совместно с onlineManager.

Поведение:

  • при возвращении фокуса окна может инициироваться проверка сети
  • при одновременном восстановлении фокуса и сети запускаются refetch-запросы
focusManager.setEventListener(handleFocus => {
  window.addEventListener('visibilitychange', () => {
    handleFocus(document.visibilityState === 'visible')
  })
})

Network Mode: стратегия выполнения запросов

TanStack Query вводит параметр networkMode, который определяет поведение запросов в зависимости от сетевого состояния.

online

Запросы выполняются только при наличии соединения. При offline они приостанавливаются.

always

Запросы выполняются независимо от сетевого статуса. Используется в специфических сценариях, где кэш или промежуточные слои могут буферизовать данные.

offlineFirst

Сначала используется кэш, затем при наличии сети выполняется синхронизация.

Пример:

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      networkMode: 'online',
    },
  },
})

Приостановленные мутации и восстановление состояния

Мутации в TanStack Query имеют собственную модель поведения при изменении сети.

Если сеть недоступна:

  • мутации переходят в paused queue
  • данные сохраняются локально
  • выполнение откладывается до восстановления соединения

После возвращения сети:

  • выполняется resumePausedMutations()
  • мутации выполняются в порядке очереди

Это обеспечивает согласованность данных даже при нестабильном соединении.

Интеграция с кастомным определением сети

В некоторых приложениях стандартного navigator.onLine недостаточно. TanStack Query позволяет переопределить логику определения сети:

import { onlineManager } from '@tanstack/query-core'

onlineManager.setEventListener(setOnline => {
  const ws = new WebSocket('wss://example.com/ping')

  ws.ono pen = () => setOnline(true)
  ws.oncl ose = () => setOnline(false)
})

Такой подход используется для:

  • проверки реальной доступности API
  • работы через WebSocket health-check
  • учета прокси или корпоративных сетей

Взаимодействие сетевого статуса и кэша

Сетевой статус не влияет напрямую на содержимое кэша, но влияет на:

  • стратегию обновления stale данных
  • триггеры refetch
  • фоновые синхронизации

Кэш остается источником синхронного состояния, а сеть — механизмом актуализации.

Поведение можно описать как разделение:

  • кэш отвечает за мгновенный доступ
  • сетевой статус отвечает за актуализацию

Сценарии деградации и устойчивость системы

При нестабильной сети TanStack Query обеспечивает:

  • сохранение последнего успешного состояния
  • отложенное выполнение операций
  • минимизацию повторных запросов
  • защиту от каскадных ошибок

Особенно важно поведение при:

  • частых переключениях online/offline
  • мобильных сетях с потерями пакетов
  • sleep/wake циклах устройства

Синхронизация состояния после восстановления сети

После перехода в online система выполняет последовательность:

  1. обновление onlineManager
  2. запуск отложенных мутаций
  3. рефетч активных запросов
  4. синхронизация stale данных
  5. обновление observers

Эта последовательность обеспечивает согласованность состояния приложения без ручной координации.

Оглавление