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

10 KiB
Raw Permalink Blame History

Обновление встроенных модулей ядра (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-релиза, незаметно отстать нельзя.

Автоматически

Обычно делать руками ничего не нужно. Подготовка стабильного релиза сама находит отставание и перегенерирует серию:

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":

    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):

    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.