# Read-only аудит failover/failback

## Короткий вывод

Штатное переключение между `primary` и `reserve` меняет маршрут **только для новых соединений**. Уже установленные TCP/UDP-соединения не переносятся и не закрываются самим Harbor.

Поэтому:

- здоровая загрузка, игра или поток продолжаются через старый канал;
- если старый канал действительно умер, существующая сессия может оборваться независимо от переключения;
- после переключения новые соединения идут через новый канал;
- бесшовной миграции уже открытого TCP/UDP-сеанса на другой внешний адрес нет.

## 1. Точный механизм

### Конфигурация

Gateway собирает один dual-channel `sing-box` config:

- `channel-primary`;
- `channel-reserve`;
- selector `channel-selector`;
- стабильные `tproxy-in` и `mixed-in`;
- отдельные diagnostic inbounds для проверки каждого канала.

Пользовательский трафик направляется в selector, а selector настроен с:

```text
interrupt_exist_connections: false
```

См. `src/server/singbox.ts:204-247`.

Роль меняется через localhost Clash API:

- `PUT /proxies/channel-selector`;
- затем Harbor читает selector обратно и подтверждает выбранную роль.

См. `src/server/services/singboxSelectorService.ts:29-81`.

Failover API доступен только в Gateway:

- `PUT /api/failover`;
- `POST /api/failover/pause`;
- `POST /api/failover/switch`;
- `POST /api/failover/check`.

См. `src/server/http/routes/failoverRoute.ts:18-39`.

Переключение selector не вызывает `sing-box` restart/apply/stop.

### Автоматический failover

`FailoverService`:

1. Проверяет оба канала через отдельные diagnostic inbound и выбранные HTTPS-сервисы.
2. Считает канал healthy только если все проверки успешны; неизвестный результат даёт `unknown`.
3. При сбое primary ждёт `failureWindowMs`.
4. Переключается на reserve только если reserve healthy.
5. При включённом traffic guard ждёт свежий quiet-window.
6. Перед самой сменой повторно проверяет здоровье и активность.
7. Выполняет selector PUT, read-back и только после этого обновляет canonical applied state.

См. `src/server/features/failover/failoverService.ts:225-245`, `:320-514`; state machine — `src/shared/failover.ts:278-354`.

Дефолты:

- проверка каждые 60 секунд;
- сбой primary — 120 секунд;
- восстановление primary — 15 минут;
- quiet-window — 30 секунд;
- активный трафик — выше 32 КБ/с;
- минимум на reserve — 10 минут;
- после 3 failover за 24 часа — карантин primary на 6 часов.

См. `src/shared/failover.ts:137-148`.

### Автоматический failback

Отдельной реализации нет: это обратная ветка той же state machine.

Из reserve Harbor возвращается на primary только после:

- полного `recoveryWindowMs`;
- `minimumReserveMs`;
- окончания quarantine, если он действует;
- quiet-window при включённом traffic guard;
- подтверждения, что primary healthy.

Причина переключения публикуется как `primary-recovered`. См. `src/shared/failover.ts:311-354`.

## 2. Судьба существующих соединений

| Событие | Уже открытый TCP/UDP flow | Новые соединения |
|---|---|---|
| Автоматический failover primary → reserve | Остаётся на прежнем outbound; Harbor его не закрывает и не мигрирует | Идут через reserve |
| Автоматический failback reserve → primary | Остаётся на reserve | Идут через primary |
| Ручной selector switch | Не закрывается, если старый outbound ещё работает | Сразу идёт через выбранную роль |
| Pause | Ничего не меняет | Идут через текущую роль |
| Disable failover | Selector и текущий маршрут не меняются; dual config временно остаётся загруженным | Идут через текущую роль |
| Обычный stop/restart/config replacement | Процесс `sing-box` останавливается, поэтому TCP/UDP-сессии прерываются | После запуска — по новой конфигурации |
| Реальная авария primary | Уже существующий flow может оборваться сам; Harbor не может перенести его на другой внешний IP | После selector switch новые flow идут через reserve |

Проверка `interrupt_exist_connections: false` непосредственно подтверждена TCP- и UDP-fixture-тестом: существующие TCP socket и UDP association продолжают обмен после switch, а новые идут через reserve. См. `test/server/singbox-selector-capability.test.js:141-142`, `:237-356`.

## 3. Отличия режимов

### Ручное переключение

`POST /api/failover/switch` вызывает selector напрямую:

- traffic guard не проверяется;
- состояние здоровья целевого канала backend не проверяет;
- после успешного ручного переключения `failoverPolicy.paused` становится `true`;
- автоматический failback не произойдёт, пока пользователь не возобновит автоматическое переключение.

См. `src/server/features/failover/failoverService.ts:248-317`, `:614-631`.

Это означает, что ручной switch может быть выполнен даже на канал, который сейчас не подтверждён healthy. Это важная оговорка.

### Автоматический failover

Автоматическое переключение:

- ждёт failure window;
- требует healthy reserve;
- при включённом guard блокируется активным или неизвестным трафиком;
- повторно валидирует условия непосредственно перед selector mutation;
- не перезапускает `sing-box`.

### Восстановление primary

Восстановившийся primary не получает новые соединения сразу. Сначала выдерживаются recovery/hold/quarantine условия и quiet-window. Пока они не выполнены, новые подключения остаются на reserve.

### Pause и Disable

`pause` приостанавливает решения, но dual config и наблюдение остаются активными.

`disable` останавливает scheduler, probes и failover activity collector, но не переключает selector и не перезапускает процесс. После обычного stop/следующего запуска собирается single-channel config.

См. `README.md:78-84`, `docs/product/application-state.md:102-110`.

## 4. Практические сценарии

- **Загрузка файла:** при обычном автоматическом failover активная передача по умолчанию задерживает switch. Если primary всё же упал, текущая TCP-загрузка не переносится на reserve; она может завершиться ошибкой. Возобновление или новый HTTP-запрос после switch пойдёт через reserve.
- **Игровая сессия:** существующий TCP-сеанс остаётся на старом канале. TCP-сессия оборвётся, если primary реально недоступен. UDP-flow также не мигрирует и может начать терять пакеты или истечь по timeout; новая сессия после switch пойдёт через reserve.
- **Стрим:** активный поток обычно блокирует автоматический switch при включённом guard. Ручной switch может быть выполнен сразу, но существующий TCP/QUIC-поток остаётся на старом outbound. При аварии старого канала плеер должен переподключиться.
- **WebSocket/долгий polling:** действующий flow не переносится; новые подключения после switch используют новую роль.
- **Молчащее соединение:** наличие открытого socket само по себе не считается активностью. Guard смотрит на дельты переданных байтов.

## 5. Условия и оговорки

- Failover реализован только для **Gateway**, не для локального Connect или `gateway-direct`.
- Активность собирается существующим `/connections` observer каждые 2 секунды, с bounded окном до 10 секунд. См. `src/server/index.ts:311-333`, `src/server/services/domainTrafficService.ts:323-416`, `:437-495`.
- Короткое соединение, полностью завершившееся между двумя снимками, может не попасть в activity guard.
- Неизвестная или устаревшая activity-информация блокирует автоматический switch; ручной switch остаётся доступен.
- Отключение traffic guard разрешает автоматический switch без ожидания тишины, но `interrupt_exist_connections: false` всё равно защищает уже открытые connections от закрытия самим selector.
- При изменении policy во время работающего single-channel VPN dual config становится `pending`; скрытого restart нет. См. `src/server/features/connection/connectionService.ts:140-201`, `:288-361`.
- Явный stop/restart или обычная смена сервера вне активного failover уже является disruptive operation: `sing-box` получает SIGTERM и текущие сессии прекращаются. См. `src/server/singboxRuntime.ts:39-62`, `:65-122`.
- Оба канала находятся в одном процессе `sing-box`; process-wide crash не защищён selector-механизмом.

## 6. Основные файлы

- `src/server/singbox.ts:204-247` — dual config, selector, inbound routing.
- `src/server/services/singboxSelectorService.ts:29-81` — selector PUT/read-back.
- `src/server/features/failover/failoverService.ts:225-245` — проверки каналов.
- `src/server/features/failover/failoverService.ts:248-317` — selector switch, commit и rollback.
- `src/server/features/failover/failoverService.ts:320-514` — автоматический раунд и traffic guard.
- `src/server/features/failover/failoverService.ts:614-631` — ручное переключение.
- `src/shared/failover.ts:137-148`, `:278-354` — дефолты и state machine.
- `src/server/services/domainTrafficService.ts:129-160`, `:323-416`, `:437-495` — классификация и activity.
- `src/server/features/connection/connectionService.ts:140-201`, `:243-361` — обычный apply/stop/restart.
- `src/server/singboxRuntime.ts:39-122` — фактическая остановка и перезапуск процесса.
- `README.md:78-84` — пользовательская документация.
- `docs/product/application-state.md:102-110` — контракт состояния.
- `workpack/tasks/TASK-021-auto-server-selection-failover.md:93-106`, `:187-204` — относящийся план и ограничения; задача не выбиралась и не изменялась.

## 7. Тесты, подтверждающие выводы

- `test/server/singbox-selector-capability.test.js:141-356`  
  Интеграционная TCP/UDP-проверка: активный трафик задерживает failover, существующие TCP/UDP продолжают работать после switch, новые соединения идут через reserve, PID процесса не меняется. Тест opt-in и пропускается без `HARBOR_SINGBOX_IMAGE`.
- `test/server/singbox-gateway-mode.test.js:69-110`  
  Проверяет selector, `interrupt_exist_connections: false`, отдельные diagnostic routes и primary/reserve outbounds.
- `test/server/failover-service.test.js:83-200`  
  Failure window, traffic guard, both-unhealthy и failback recovery/hold/quarantine.
- `test/server/failover-service.test.js:255-420`  
  Disabled zero-work, отмена устаревших наблюдений и непосредственная revalidation активности.
- `test/server/failover-service.test.js:423-520`  
  Selector rollback, commit ordering и ручной switch с pause.
- `test/server/domain-traffic.test.js:209-239`  
  Activity считается по пользовательскому VPN traffic, diagnostic connection не блокирует switch.
- `test/server/connection-service.test.js:265-310`, `:340-390`  
  Restart dual config и rollback; pending edits для работающего single-channel.
- `test/server/singbox-runtime.test.js:16-50`  
  При изменении config runtime запускает новый процесс.
- `test/server/failover-route.test.js:10-53`  
  Gateway-only API и маршруты ручного switch/pause/check.
- `test/web/failover-feature-contract.test.js:19-76`  
  UI явно сообщает: новые подключения переключаются, открытые остаются на прежнем канале.

## Review findings и residual risks

- **medium — `src/server/features/failover/failoverService.ts:614-620`:** ручной switch не проверяет health целевого канала и не применяет traffic guard; он сразу меняет selector и ставит automation на pause.
- **medium — `test/server/singbox-selector-capability.test.js:141-356`:** capability test opt-in и использует deterministic `direct` outbounds, а не реальный VLESS/Trojan outage.
- **medium — `src/server/services/domainTrafficService.ts:414-416`, `:451-479`:** activity основана на polling и byte deltas; короткие или очень малые потоки могут не блокировать автоматическое решение.
- **info — `src/server/singboxRuntime.ts:39-122`:** явный stop/restart отличается от selector switch и прерывает существующие соединения.
- **info — архитектура одного процесса:** падение всего `sing-box` не компенсируется selector failover.

Файлы не изменялись. Тесты и live Gateway в рамках read-only аудита не запускались.