HY2XS_flamy/docs/11-testing-and-acceptance.md

# Testing and acceptance

## Цель документа

Зафиксировать checklist для новой двухслойной схемы.

## Как запускать тесты

```bash
# Юнит-тесты и типы оркестратора
cd orchestrator && bun install --frozen-lockfile && bun run check && bun test

# Тесты и статический анализ HY2XS admin
cd apps && go vet ./... && go test ./...

# Полный E2E с реальным клиентом Hysteria (Debian 13 amd64)
HYSTERIA_BIN=/usr/local/bin/hysteria ./tools/test/e2e-hysteria.sh

# Production-сборка: прогоняет тесты, резолвер и compatibility gate
./tools/build/build.sh
```

`build.sh` останавливается, если падают тесты оркестратора, тесты админки или compatibility gate.

## A. Builder layer tests

### Проверяем
1. builder запускается на Debian 13 amd64 build host
2. итоговый пакет собирается без target-side шагов
3. bundled HY2XS admin реально входит в пакет
4. package metadata / build id присутствуют
5. compiled Bun/TypeScript orchestrator artifact присутствует
6. в пакет не попадает build-мусор
7. builder сам доставляет отсутствующие build-зависимости
8. builder проверяет версии Go/Bun/Node.js/pnpm
9. builder пишет версии toolchain в metadata
10. builder прогоняет `bun test` и `go test` до упаковки

## A1. Latest-stable resolver

Фикстуры и ожидаемое поведение (`orchestrator/test/hysteria-release.test.ts`):

| Сценарий | Ожидание |
| --- | --- |
| stable `app/v2.12.2` | выбирается |
| prerelease `app/v2.13.0` | игнорируется |
| draft `app/v2.14.0` | игнорируется |
| чужое семейство тегов (`core/`, `docs/`) | игнорируется |
| тег без префикса `app/` | игнорируется |
| `app/v2.9.10` против `app/v2.9.2` | выбирается `2.9.10` (числовое сравнение, не строковое) |
| отсутствует `hysteria-linux-amd64` | ошибка |
| дублирующийся `hysteria-linux-amd64` | ошибка, а не случайный выбор |
| non-https URL артефакта | ошибка |
| невалидный semver в теге | игнорируется |
| пустой список релизов | понятная ошибка |
| несовпадение SHA-256 | сборка падает |
| сетевая ошибка / rate limit | понятная ошибка с подсказкой про `GITHUB_TOKEN` и `HYSTERIA_CHANNEL=pinned` |

Отдельно проверяется, что **`latest stable` — это именно stable, а не максимальная строка или самый свежий тег**.

## A2. Release rollover

Ключевой acceptance-критерий модели «latest на сборке»:

```text
Сегодня:  latest = 2.12.2  →  пакет A закрепляет 2.12.2
Завтра:   latest = 2.12.3  →  пакет B закрепляет 2.12.3

Повторная установка пакета A всё равно ставит 2.12.2
```

Проверяется на двух уровнях:
- резолвер даёт разный результат на разных снимках upstream (`orchestrator/test/release-rollover.test.ts`);
- install-time код не импортирует резолвер, не обращается к `api.github.com` и не использует moving `latest` — это утверждение проверяется тестом и acceptance-шагом сборки.

## A3. Compatibility gate

1. скачанный артефакт проходит проверку SHA-256;
2. `hysteria version` совпадает с разрешённой версией;
3. реальный бинарник принимает канонический конфиг HY2XS для Gecko;
4. то же для Salamander;
5. при несовместимости падает **сборка** с сообщением `BUILD FAILED: unsupported Hysteria stable vX.Y.Z`, а не установка у пользователя.

## A4. Конфигурационный контракт (unit)

Таблица `orchestrator/test/env.test.ts`:

| Вход | Ожидание |
| --- | --- |
| значение не задано | `gecko` |
| `gecko` | принято |
| `salamander` | принято |
| неизвестный тип | отклонено |
| `Gecko` (регистр) | отклонено |
| gecko `max < min` | отклонено |
| gecko `max > 2048` | отклонено |
| gecko `max == 2048` | принято |
| неположительный/нецелый `min` | отклонено |
| пустой obfs-пароль | автогенерация, а не пустое значение в конфиге |
| `HY2XS_CONFIG_SCHEMA_VERSION=1` | отклонено с указанием на чистую установку |

Отдельно — round-trip `parse(render(config)) == config`. Этот тест ловит класс ошибок «в рендер runtime-конфига попал литерал вместо значения из конфигурации».

Рендер конфига (`orchestrator/test/render-config.test.ts`):

- Gecko рендерит **только** gecko-подблок;
- Salamander рендерит **только** salamander-подблок;
- в конфиге никогда нет двух подтипов obfs одновременно;
- шаблон не содержит захардкоженного типа обфускации;
- пароль с пробелами и спецсимволами экранируется;
- YAML-инъекция через пароль отклоняется даже в обход env-валидации.

## B. Target install tests

### На чистом Debian 13 проверяем
1. пакет запускается без ручной сборки на сервере
2. Hysteria2 скачивается с official upstream
3. bundled HY2XS admin раскладывается локально из пакета
4. создаются нужные каталоги
5. создаются systemd unit-файлы
6. создаются `hy2xs.env` и `post-install.env` с правами `0600 root:root`
7. baseline firewall применяется корректно через staged mode
8. SSH остаётся доступным
9. `reconfigure --dry-run` выводит план изменений
10. `reconfigure --apply` применяет изменения и проходит smoke

## C. Runtime tests

1. `hysteria-server` active
2. `hy2xs-admin` active
3. Hysteria слушает только IPv4 (`0.0.0.0:<udp_port>`)
4. HY2XS admin слушает ожидаемый `HY2XS_UI_BIND_HOST:<ui_port>`
5. тестовый совместимый клиент подключается
6. идёт реальный трафик
7. лимит 50/50 Mbps соблюдается при согласованной клиентской конфигурации
8. reboot не ломает baseline
9. Hysteria2 управляется systemd unit, а не внутренним updater'ом admin panel
10. нет IPv6 listen (`[::]`) для Hysteria/HY2XS admin
11. `trafficStats.secret` не равен `JWT_SECRET`
12. bootstrap admin secret существует и имеет `0600`
13. `trafficStats` API: корректный secret принимает запрос, неверный secret отклоняется
14. TLS mode в `config.yaml` соответствует runtime env (`acme|file|self_signed_dev`)
15. при `HY2XS_TLS_MODE=acme` в `config.yaml` выставлен `acme.type` из `HY2XS_ACME_TYPE`
16. direct `hysteria2://` node URL в API/QR формируется по `HY2XS_PUBLIC_HOST` + `HY2XS_PUBLIC_PORT`; subscription delivery endpoint отключён в baseline и не входит в acceptance
17. `nft -c -f /etc/nftables.conf` проходит после apply
18. пароль admin и `con_pass` не перезаписываются при рестарте `hy2xs-admin`
19. остановка/рестарт UI не останавливает `hysteria-server`
20. traffic accounting/kick ориентируются на systemd status, а не на SQLite `HYSTERIA2_ENABLE`
21. `/etc/hysteria/config.yaml` имеет `0640 hysteria:hy2xs-admin`
22. `hy2xs-admin` может читать `/etc/hysteria/config.yaml`, но не может писать

## C1. Семантический smoke конфига

Недостаточно `grep` по YAML: он не отличит нужное поле от такой же строки в другой секции и не заметит оставшийся рядом лишний подблок.

Smoke разбирает `/etc/hysteria/config.yaml` и сверяет с production-профилем:

```text
effective Hysteria version == версия из metadata пакета

obfs:
  type == HY2XS_HYSTERIA_OBFS_TYPE
  ровно один подблок, соответствующий type
  password непустой
  для gecko: minPacketSize == 512, maxPacketSize == 1200

bandwidth:
  up/down == runtime env
  disableLossCompensation == false

congestion:
  type == bbr
  bbrProfile == standard

quic:
  disableStatelessReset == false
  окна и таймауты == baseline

trafficStats:
  listen == runtime env
  secret непустой

auth:
  type == http
  url содержит machine access_token

TLS:
  acme-режим не содержит секции tls
  file-режим не содержит секции acme
```

## C2. End-to-end с реальным клиентом

`tools/test/e2e-hysteria.sh`, отдельно для Gecko и Salamander:

1. сервер принимает сгенерированный конфиг и стартует;
2. TLS handshake;
3. handshake с обфускацией;
4. HTTP auth HY2XS: разрешённый пир принят;
5. HTTP auth HY2XS: неразрешённый пир отклонён;
6. клиент подключается **именно по сгенерированной `hysteria2://` ссылке**;
7. TCP forwarding;
8. UDP forwarding;
9. `trafficStats` с валидным secret;
10. `trafficStats` с невалидным secret отклоняется;
11. per-peer accounting содержит аутентифицированного пира;
12. перезапуск сервера;
13. быстрое переподключение клиента (поведение stateless reset).

Пункт 6 — тот самый, который ловит класс ошибок, неизбежный при наивном включении Gecko: сервер работает, ссылка формально валидна, а клиент по ней не подключается.

## C3. Share URI (unit)

`apps/service/hysteria2_api_test.go`:

- Gecko URI содержит `obfs=gecko` и `obfs-password`;
- Salamander URI содержит `obfs=salamander` и `obfs-password`;
- конфиг без обфускации даёт ссылку без `obfs`;
- неизвестный тип обфускации в ссылку не попадает;
- обфускация без пароля в ссылку не попадает;
- SNI: ACME-домен → `HY2XS_DOMAIN` → `HY2XS_PUBLIC_HOST`, IP не используется;
- спецсимволы в credentials и obfs-пароле переживают round-trip: `+`, пробел, `#`, `@`, `/`, `?`, `&`, `=`, `%`, кириллица;
- литеральный `+` кодируется как `%2B` и не схлопывается с пробелом (регрессия на upstream-баг 2.9.3).

## C4. Экспорт конфига (unit)

`apps/service/hysteria2_export_test.go`:

- неизвестные upstream-секции переживают экспорт целиком, включая вложенные карты и списки;
- операционные поля остаются читаемыми;
- вырезаются: obfs-пароль, `trafficStats.secret`, `access_token`, `auth.userpass`, учётные данные ACME DNS, пароли outbound;
- вырезается **неизвестное** поле с секретным именем;
- пути к файлам (`tls.key`, `ech.keyPath`, `clientCA`) остаются видимыми.

## D. Negative tests

1. не Debian 13
2. порт уже занят
3. старое конфликтующее состояние уже существует
4. домен / SNI заданы некорректно
5. bundled UI отсутствует в пакете
6. Hysteria upstream недоступен
7. firewall применился частично
8. install flow прерван посередине
9. попытка использовать `HY2XS_IPV6_ENABLED=true`
10. `HY2XS_PUBLIC_HOST=0.0.0.0`
11. неизвестный `HY2XS_HYSTERIA_OBFS_TYPE`
12. конфигурация со схемой `HY2XS_CONFIG_SCHEMA_VERSION` из линейки `0.x`
13. upstream `latest` несовместим с шаблоном HY2XS — падает сборка, не установка

## E. Fix20 production matrix (обязательные сценарии)

1. **Clean Debian 13 minimal**:
   - только SSH, без ручной установки зависимостей;
   - default `/etc/nftables.conf` stub;
   - install проходит полностью;
   - `doctor`/`status` показывают рабочее состояние.

2. **Non-systemd container**:
   - fail-fast до destructive шагов;
   - диагностическое сообщение с причиной capability/systemd.

3. **Foreign nftables**:
   - при `HY2XS_FIREWALL_MODE=managed` install/reconfigure блокируются;
   - при `HY2XS_FIREWALL_MODE=takeover` создаются backup/rollback guard и apply проходит.

4. **Rollback guard cleanup**:
   - после успешного apply/smoke не остаются `hy2xs-fw-rollback-*.timer/.service`.

5. **Partial install + repair**:
   - состояние `install-state` фиксирует промежуточную фазу;
   - `repair` завершает граф до `installed=true`.

6. **AAAA при IPv4-only**:
   - policy строго валидируется preflight;
   - soft warning path не используется в production baseline.

7. **Slow-start admin readiness**:
   - install не падает на race после restart;
   - readiness waiters дожидаются listener/healthz.

## Acceptance criteria

Система принимается, если:

1. production builder на Debian 13 amd64 выдаёт переносимый install package
2. target server не выполняет build step
3. Hysteria2 получена из official upstream
4. HY2XS admin поставлен из install package
5. `post-install.env` отражает фактическое deploy-состояние
6. оркестратор зафиксирован как Bun/TypeScript stack и поставляется как готовый install-артефакт
7. оркестратор не требует standalone update / rollback / uninstall subcommands
8. bounded rollback в install/reconfigure корректно отрабатывает failure-сценарии firewall/systemd/config/smoke
9. Telegram/access layer не требуется для прохождения install acceptance
10. отсутствует production path для port hopping
11. UI не запускается от root
12. клиентские endpoint не зависят от request `Host`/`hostname`
13. production build verify падает, если `config/hy2xs.env` содержит placeholder-значения
14. production build verify падает при dirty git tree (кроме `ALLOW_DIRTY_BUILD=true`)
15. metadata содержит `source_git_commit`, `dirty_tree`, `build_profile=production`
16. builder без override на сегодняшний день автоматически выбирает последнюю стабильную версию Hysteria
17. собранный пакет содержит **точные** версию, URL и SHA-256
18. выход новой версии Hysteria после сборки не меняет содержимое старого пакета
19. новая установка генерирует Gecko
20. Gecko использует `512/1200`
21. установленная Hysteria реально принимает сгенерированный YAML
22. сервис запускается под существующим непривилегированным пользователем `hysteria`
23. созданный пользователь получает `hysteria2://` с `obfs=gecko` и `obfs-password`
24. совместимый клиент Hysteria подключается напрямую по этой ссылке
25. после перезапуска Hysteria клиент быстро восстанавливает соединение
26. режим `HY2XS_HYSTERIA_OBFS_TYPE=salamander` полностью работоспособен
27. admin читает Gecko-конфиг без ошибок
28. экспорт не уничтожает современные и неизвестные upstream-поля
29. экспорт не содержит секретов
30. frontend отображает Gecko
31. `namedotcom` удалён, актуальные ACME-провайдеры отражены
32. документация нигде не утверждает, что Salamander — фиксированный инвариант
33. документация не фиксирует конкретный номер версии как «текущую версию», а объясняет latest-stable build policy
34. форма создания пира содержит примеры значений и пояснения для полей «Пир», «Комментарий» и «Секрет»