ZapretKVN-android/docs/CORE_UPDATE.md
loop-uh f08d9b73f6
Some checks failed
Android CI / build (push) Has been cancelled
Core: official Hysteria app/v2.14.0 (patch 0015) and four fixes of the automatic updater
The updater had never run since the sing-box-extended 2.7.3 move: its byte-for-byte proof failed on
mixed 7/8-character index hashes, the quic-go version swap missed the indirect-to-direct move of
patch 0006, a blank context line counted as a change, and indirect requirements the new Hysteria no
longer needs were not pruned. All four are fixed and tested (test-update-hysteria-core.sh).
Hysteria 2.14.0 needs apernet/quic-go v0.65.1: patch 0015 adapts our server.Outbound test double and
applies a four-line adaptation of Xray's MASQUE transport in prepare.sh, the first local change of
Xray protocol code (owner decision 2026-11-15, documented in CORE_UPDATE.md).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-15 07:05:06 -05:00

125 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Обновление встроенных модулей ядра (Hysteria и другие Go-зависимости патчей)
sing-box-extended на Android собирается из исходников с серией патчей
`core-patches/0001…0005`. Часть зависимостей живёт не в `core.properties`, а в
`go.mod`/`go.sum`, которые эти патчи добавляют. Так устроена официальная
Hysteria: `github.com/apernet/hysteria/{core,extras}/v2` вшиты в libbox патчем
`0003-official-hysteria2-core.patch`, а `0005` снова трогает соседние строки
`go.mod`. Поэтому новая версия Hysteria — это перегенерация серии, а не правка
одной строки.
Какую версию брать, решает Windows: `scripts/resolve_core_versions.py` в
репозитории windows выбирает последний стабильный `app/vX.Y.Z`, а
`check_core_release_freeze.py` требует тот же `HYSTERIA_CORE_TAG` на Android.
Отставание останавливает подготовку Android-релиза, незаметно отстать нельзя.
## Автоматически
Обычно делать руками ничего не нужно. Подготовка стабильного релиза сама
находит отставание и перегенерирует серию:
```bash
scripts/prepare-stable-core.sh vMAJOR.MINOR.PATCH
```
Она берёт последний стабильный релиз Windows, запускает общую
`prepare_core_release.py`, а та при отставании Android вызывает
`scripts/update_hysteria_core.py --tag app/vX.Y.Z --write`. Скрипт выполняет
процедуру ниже во временной копии и пишет в репозиторий, только если прежние
патчи воспроизводятся байт в байт, `go mod tidy -diff` не требует изменений
`go.mod`, а затронутые пакеты компилируются с боевыми тегами. `libbox.aar`
после смены пинов пересобирает preBuild-хук Gradle. Отдельно обновление
запускается так же: без `--write` — только проверка.
Автоматика отказывает и ничего не пишет, когда новая Hysteria меняет состав
модулей `go.mod`, требует новых `// indirect`-строк, конфликтует с патчами вне
`go.mod`/`go.sum` или не компилируется. Тогда остаётся ручная процедура.
## Процедура (вручную, если автоматика отказала)
1. Копия исходников ядра (не `git clone --shared`: `core-build/source` —
неглубокий клон), в скриптах только `git -C "$SB"`:
```bash
cp -a core-build/source "$SB"
```
2. Серия патчей цепочкой коммитов с тегами `p0000`…`p0005` (`git apply` +
`commit` по порядку из `core-patches/series.sha256`). Проверка настройки
диффа: `git -C "$SB" diff --abbrev=8 p0002 p0003` байт в байт совпадает с
`0003-official-hysteria2-core.patch` — тогда в новых патчах изменится только
то, что вы поменяли.
3. На `p0003`, с тем Go, что в `GO_VERSION` (`GOTOOLCHAIN=local`):
```bash
go get github.com/apernet/hysteria/core/v2@vX.Y.Z github.com/apernet/hysteria/extras/v2@vX.Y.Z
```
`go get` поднимает и транзитивные зависимости (quic-go, testify). Проверьте
`go mod tidy -diff`: если он требует новую `// indirect`-строку в `go.mod`,
добавьте только её. Полный `tidy` на этом шаге не запускать — он перестраивает
блоки из `0001`. Из `go.sum` уберите только хеши прежней Hysteria и прежнего
quic-go.
4. `git cherry-pick p0004 p0005`. В `0005` ожидаем конфликт в `go.mod`: он
переносит amneziawg-go из косвенных в прямые, а рядом стоит quic-go. Итог:
строки amneziawg в блоке `// indirect` нет, quic-go — новый.
5. На финальном состоянии (после `protocol/xraycore/prepare.sh`):
`go mod tidy -diff` не требует изменений `go.mod`, а
`go test -count=1 -run '^$' -tags … ./protocol/hysteria2 ./protocol/xraycore
./parser/link ./route/rule ./transport/wireguard` компилируется.
6. Новые патчи — `git diff --abbrev=8` между соседними тегами; пересчитать
`core-patches/series.sha256`, `CORE_PATCH_SHA256`, `HYSTERIA_CORE_TAG`,
`HYSTERIA_CORE_COMMIT` (`go mod download -json …@vX.Y.Z` → `Origin.Hash`),
обновить версию в `docs/THIRD_PARTY_NOTICES.md` и
`app/src/main/res/raw/third_party_notices.txt` (файлы одинаковые).
7. Полный `scripts/build-core.sh` (Go из `GO_VERSION` первым в `PATH`,
`ANDROID_HOME`), затем unit-тесты и `scripts/verify-project.sh`.
## Что умеет и чего не умеет автоматика (2026-11-15, переход на app/v2.14.0)
Первый запуск `update_hysteria_core.py` после перехода на sing-box-extended 2.7.3 показал четыре скрытых дефекта; все
исправлены и покрыты `scripts/test-update-hysteria-core.sh` (входит в `verify-project.sh`):
- Серия писалась в несколько заходов: патчи 0001-0008 с 7-символьными хешами в строках `index`, 0009 и дальше с 8.
Доказательство «каждый патч воспроизводится из цепочки коммитов» теперь сравнивает всё, кроме самих хешей `index`
(их `git apply` не читает, а перенесённые на новую базу патчи хранят хеши старой), и диффит каждый патч той длиной
хеша, с которой он записан. Изменённый хунк или режим файла по-прежнему отказ.
- Подмена версии при конфликте `go.mod` теперь не зависит от `// indirect`: патч 0006 переносит quic-go из косвенных в
прямые, и старая версия оставалась в итоговом `go.mod`.
- Пустая строка контекста в `go mod tidy -diff` считалась изменением.
- Новая Hysteria может перестать нуждаться в косвенных зависимостях серии (2.14.0: пять строк). Если `tidy` требует
только удалить строки `// indirect`, они удаляются в последнем патче серии (его дифф показывает удаление, прежние
патчи не меняются). Любое другое требование `tidy` остаётся отказом.
`--keep КАТАЛОГ` оставляет рабочую копию (каталог не должен существовать) для разбора отказа.
Если новая Hysteria меняет API, нужен ПОВТОРНЫЙ патч серии, а не правка выпущенных. Для 2.14.0 это
`0015-hysteria-2-14-api-and-xray-quic-go.patch`: тестовый двойник `server.Outbound` под новую сигнатуру
(`*RequestInfo` в `TCP`/`UDP`/`CheckUDP`) и `protocol/xraycore/xray-quic-go-http-stream.patch`, который `prepare.sh`
применяет к скопированному исходнику Xray. Это ПЕРВОЕ локальное изменение кода протокола Xray и исключение из правила
«копируется без правок» (решение владельца 2026-11-15): официальная Hysteria 2.14.0 требует apernet/quic-go v0.65.1,
а Xray v26.11.9 написан под v0.61.1, и один вызов транспорта MASQUE (`HTTPStream()`) возвращает лишнюю ошибку.
`git apply` отказывает, если контекст исходника Xray изменился. Исключение снимается, когда закреплённый Xray
собирается с quic-go, который требует Hysteria: тогда удалить патч Xray и шаг в `prepare.sh`.
## Версия Go
`GO_VERSION` на Android и `amnezia.toolchain` в `core-lock.windows-x64.json`
обязаны совпадать (`check_core_release_freeze.py`). Поднимаются вместе: toolchain
ставится в `~/.local/share/toolchains/go-X.Y.Z` (SHA-256 из
`https://go.dev/dl/?mode=json`), `/usr/local/bin/go` переключается после коммита
пинов, в `.forgejo/workflows/*.yml` меняется `go-version`.
## Xray pin (added 2026-11-09)
Android builds Xray from source, so its pin is moved by hand: edit `XRAY_CORE_MODULE` / `XRAY_CORE_COMMIT` in `core.properties`
(Xray stopped publishing Go-module tags after `v1.260327.0`, so use the commit's pseudo-version from
`go list -m -json github.com/xtls/xray-core@<commit>`), add a NEW core patch for any source or `go.mod` change (see `0014`), and
check which Go version the release needs (`go` line of its `go.mod`; the pair shares one toolchain). The freeze
(`windows/scripts/prepare_core_release.py`) now compares the Android commit with the commit of the Windows-selected Xray tag and
stops when Android lags, so the pin cannot fall behind silently again.