Skip to content

OFFLINE_SUPPORT.md

Latest commit

 

History

History
125 lines (95 loc) · 5.5 KB

OFFLINE_SUPPORT.md

File metadata and controls

125 lines (95 loc) · 5.5 KB

Offline-First Architecture

Обзор

Приложение полностью работает без интернета, используя Service Worker для кэширования и offline-first стратегию.

Как это работает

1. Service Worker Caching (public/sw.js)

Статические активы (HTML, CSS, JS)

  • Стратегия: Network-first → Cache fallback
  • При загрузке страницы пытается взять свежую версию с сервера
  • Если сеть недоступна - возвращает закэшированную версию
  • Успешные ответы автоматически кэшируются

GitHub API запросы

  • Стратегия: Cache-first (с синхронизацией)
  • Сначала проверяет наличие данных в кэше
  • При наличии - возвращает сразу (быстро)
  • При отсутствии - делает запрос и кэширует результат
  • Если сеть недоступна и нет в кэше - возвращает ошибку 503

2. Индикатор Offline-статуса (src/components/OfflineIndicator.tsx)

  • Автоматически отображается в левом нижнем углу экрана
  • Показывает "Offline mode - viewing cached data"
  • На основе navigator.onLine API
  • Исчезает, когда интернет восстановлен

3. Обработка ошибок

Функции-помощники в src/lib/utils.ts:

  • isOfflineError(error) - определяет, является ли ошибка offline-ошибкой
  • getOfflineErrorMessage(operation) - возвращает пользовательское сообщение

Кэши

github-api-cache-v2

Хранит響:

  • Результаты listFiles('topics')
  • Результаты listFiles('posts')
  • Один прочитанный файл (MD контент)
  • Метаданные фум

Размер: Зависит от кол-ва загруженных тем/постов

static-cache-v2

Хранит:

  • index.html
  • sw.js
  • И другие static assets

Использование в разработке

Очистить весь кэш (console)

window.clearGitHubApiCache()

Проверить кэш (DevTools)

Application → Cache Storage → github-api-cache-v2 / static-cache-v2

Включить offline режим (DevTools)

Network → Throttling → Offline
или
DevTools → More tools → Network conditions → Offline

Поведение offline

Сценарий Поведение
Открыта уже загруженная страница Работает нормально (из кэша)
Попытка загрузить новые данные Показывает ошибку "Offline"
Интернет вернулся Приложение автоматически начнёт загружать свежие данные
Переход по ссылке при offline Показывает Outlet с ошибкой-сообщением

Ограничения offline

❌ Не работает:

  • Загрузка новых топиков/постов при их отсутствии в кэше
  • Авторизация (если токен не сохранён)
  • Создание новых постов/тем
  • Редактирование профиля
  • Загрузка новых форумов

✅ Работает:

  • Просмотр загруженных топиков
  • Просмотр загруженных постов
  • Просмотр профилей (если уже загружены)
  • Чтение постов и комментариев
  • Смена темы (light/dark)
  • Смена языка

Типичный workflow

  1. Первая загрузка → все данные загружаются и кэшируются
  2. Повторные посещения → быстрая загрузка из кэша
  3. Потеря интернета → продолжение работы с кэшированными данными + offline-индикатор
  4. Восстановление сети → автоматическое обновление при новых запросах
  5. Очистка кэша → можно сделать вручную через window.clearGitHubApiCache()

Что изменилось в коде

Service Worker (public/sw.js)

  • ✅ Network-first для статики (быстрее)
  • ✅ Cache-first для GitHub API (работает offline)
  • ✅ Graceful fallback при недоступности сети
  • ✅ Обновлены версии кэша (v1 → v2)

React компоненты

  • ✅ Добавлен OfflineIndicator компонент
  • ✅ Обновлён Layout для отображения offline-статуса
  • ✅ Добавлены helper-функции для offline-ошибок

Безопасность

  • Токен GitHub хранится в IndexedDB (защищённо)
  • Offline-кэш НЕ содержит токен или приватные данные
  • Все API запросы требуют валидного токена
  • Закэшированные ответы - только публичные данные