460 строк · 41 КиБ
code/crates/chl-epic/CHUNKED-INSTALL-DESIGN.md
| 1 | # Установка игр Epic: чанковый протокол — что это, чего он стоит и что делать |
| 2 | |
| 3 | Это ответ на единственный незакрытый пункт фазы 3 |
| 4 | ([ROADMAP](../../../ROADMAP.md), «Epic: установка и запуск игр (чанковый |
| 5 | протокол)») и на самый крупный пробел, найденный аудитом: лаунчер умеет |
| 6 | показать каталог Epic и запустить игру, **уже скачанную Heroic или |
| 7 | legendary**, но скачать новую не умеет вообще — загрузочного конвейера нет |
| 8 | ни в каком виде. |
| 9 | |
| 10 | Формат и тон — как у [`CAS-DESIGN.md`](../chl-wine/CAS-DESIGN.md): сначала |
| 11 | находки, потом решение с обоснованием, в конце честный список того, что в |
| 12 | этом проходе сделано, а что осталось текстом. Как и там, **основной |
| 13 | результат этого прохода — не код, а разобранный вопрос**; кода написан |
| 14 | ровно один безопасный кусок, и ниже сказано, почему именно он. |
| 15 | |
| 16 | ## Главная находка: задача делится на две части с разной ценой ошибки |
| 17 | |
| 18 | Разбирая `sw_dlm.py` (2314 строк, копия кода legendary в StartWine) и |
| 19 | живой `legendary 0.21.0`, обнаруживается, что «чанковый протокол» — это на |
| 20 | самом деле две очень разные задачи, которые принято обсуждать как одну: |
| 21 | |
| 22 | | | Разбор манифеста | Загрузка и сборка | |
| 23 | |---|---|---| |
| 24 | | Что делает | читает буфер из сети в память | пишет гигабайты на диск | |
| 25 | | Цена ошибки | ошибка разбора → отказ, ничего не испорчено | ошибка сборки → **испорченная установленная игра** | |
| 26 | | Можно проверить без аккаунта Epic? | **да**, на синтетическом манифесте | нет, нужна настоящая игра и настоящий трафик | |
| 27 | | Объём | ~1200 строк вместе с тестами | ~1600 строк в legendary, плюс докачка, ремонт, дельты | |
| 28 | | Есть ли готовое? | есть (см. ниже), но своё написать реально | есть, и переписывать его — многонедельная работа | |
| 29 | |
| 30 | Из этой таблицы и следует всё остальное в документе. Аудит записал |
| 31 | «чанковый протокол» одной строкой как единый пробел; на деле его левая |
| 32 | колонка закрывается за один проход и безопасно, а правая — это отдельный |
| 33 | проект с риском для пользовательских данных. |
| 34 | |
| 35 | ## Что удалось выяснить про сам формат |
| 36 | |
| 37 | Публичной спецификации у Epic нет — ни документа, ни RFC, ни разбора в |
| 38 | блоге. Формат — часть `FBuildPatchServices` в Unreal Engine; в открытом |
| 39 | API движка документировано только существование `EFeatureLevel`, но не |
| 40 | сериализация. Всё, что известно, восстановлено сторонними разработчиками |
| 41 | из бинарников. Де-факто спецификация — исходник |
| 42 | [legendary](https://github.com/derrod/legendary), и именно поэтому копия |
| 43 | этого кода лежит в StartWine с явной лицензионной шапкой GPL-3. |
| 44 | |
| 45 | Форма проверена не по пересказу, а по байтам (см. «Как перепроверить»): |
| 46 | |
| 47 | ```text |
| 48 | заголовок, 41 байт, никогда не сжат: |
| 49 | magic u32 = 0x44BEC00C |
| 50 | header_size u32 ← читать отсюда, а не считать за 41 |
| 51 | size_uncompressed u32 |
| 52 | size_compressed u32 |
| 53 | sha1 [20] ← от РАСПАКОВАННОГО тела |
| 54 | stored_as u8 ← бит 0: zlib; бит 1: шифрование (версия 22+) |
| 55 | version u32 ← feature level |
| 56 | тело, четыре секции подряд, каждая со своим размером и своей версией: |
| 57 | ManifestMeta | ChunkDataList | FileManifestList | CustomFields |
| 58 | ``` |
| 59 | |
| 60 | Что в этой форме важно и неочевидно: |
| 61 | |
| 62 | - **У каждой секции свой размер в байтах.** Это не избыточность, а |
| 63 | механизм совместимости: манифест более новой версии дописывает поля в |
| 64 | конец секции, а читатель обязан прочитать известное и перешагнуть |
| 65 | остальное по объявленному размеру. Реализация в `manifest.rs` |
| 66 | пользуется этим явно (`Reader::section`), поэтому неизвестная будущая |
| 67 | версия теряет незнакомые поля, а не ломает чтение целиком. |
| 68 | - **Списки хранятся «по столбцам», а не по записям.** Сначала все GUID |
| 69 | подряд, потом все хэши подряд, потом все sha1 — и так шесть проходов |
| 70 | для чанков, шесть-девять для файлов. Разбор обязан идти теми же |
| 71 | проходами; попытка читать «запись за записью» даёт мусор, который |
| 72 | выглядит как данные. |
| 73 | - **Строки — знаковая длина.** Положительная — ASCII с нулём на конце, |
| 74 | отрицательная — UTF-16LE (длина в символах, не в байтах), ноль — |
| 75 | пустая. Отрицательный случай не встречается ни в одном англоязычном |
| 76 | манифесте и появляется на первом же файле с нелатинским именем внутри |
| 77 | игры. Наивный разбор на нём молча уезжает по смещению и продолжает |
| 78 | «успешно» читать мусор. Это ровно тот класс ошибки, ради которого в |
| 79 | эталонный манифест намеренно вставлено имя `Content/Тексты/описание.txt`. |
| 80 | - **Смещение части внутри файла в манифесте не записано.** Оно |
| 81 | накапливается по порядку частей. Ошибиться здесь особенно неприятно: |
| 82 | файл соберётся из правильных байт в неправильном порядке, размер |
| 83 | сойдётся, и ни одна проверка длины этого не заметит. |
| 84 | - **`data_version` растит `ManifestMeta` (build_id при ≥1, поля удаления |
| 85 | при ≥2), а версия `FileManifestList` растит запись файла** (md5 и |
| 86 | mime-тип при ≥1, sha256 при ≥2). |
| 87 | - **Номер группы чанка — это crc32 от GUID по модулю 100.** Он и записан |
| 88 | в манифесте, и выводится вычислением; проверено, что оба способа дают |
| 89 | одно и то же. Ошибка здесь означает поход за чанком не в тот подкаталог |
| 90 | CDN и 404 на ровном месте. |
| 91 | - **Имя чанка на CDN** — |
| 92 | `{ChunksV2|V3|V4}/{группа:02}/{хэш:016X}_{GUID}.chunk`, каталог выбирается |
| 93 | по feature level (≥15 → V4, ≥6 → V3, ≥3 → V2). Базовый адрес берётся из |
| 94 | ответа сервера, а не из манифеста. |
| 95 | - **Хэш чанка — собственный «катящийся» хэш Epic**, не sha и не crc: |
| 96 | таблица на 256 значений по полиному `0xC96C5795D7870F42`, состояние |
| 97 | прокручивается влево на бит перед xor на каждом байте. Он входит в имя |
| 98 | файла и им же чанк проверяется после скачивания. |
| 99 | - **Магическое число отдельного чанка — `0xB1FE3AA2`**, заголовок версий |
| 100 | 1–3, тело zlib. Проверено по исходнику напрямую: в одном из сторонних |
| 101 | обзоров это число приведено с опечаткой, десятичное `2986228386` — |
| 102 | верное. |
| 103 | - **Начиная с версии 22 тело манифеста может быть зашифровано** (AES-GCM, |
| 104 | бит 1 в `stored_as`, плюс secret GUID и тег в заголовке). В копии |
| 105 | legendary внутри StartWine этого ещё нет — это из свежей версии, и |
| 106 | проверить на живых байтах здесь было не на чем. Реализация поэтому |
| 107 | такой манифест **явно отвергает с внятным текстом**, а не пытается |
| 108 | разобрать: молча разобранный шифротекст выглядел бы как данные. |
| 109 | - **Существует ещё и JSON-вариант манифеста** для части старых игр, со |
| 110 | своей знаменитой странностью: числа закодированы как склейка |
| 111 | трёхзначных десятичных групп по байту, little-endian. Разбора для него |
| 112 | здесь нет; попытка скормить его парсеру даёт понятную ошибку, а не |
| 113 | «нет магического числа». |
| 114 | |
| 115 | ## Готовое в Rust: есть, но не то, чего не хватает |
| 116 | |
| 117 | Проверено до того, как писать своё, — потому что разбор недоверенного |
| 118 | двоичного формата из сети это ровно тот код, который не стоит писать без |
| 119 | нужды. |
| 120 | |
| 121 | **Полного решения на Rust не существует.** Ни одного крейта, который берёт |
| 122 | на себя весь путь «манифест → чанки с CDN → собранные файлы». Что есть: |
| 123 | |
| 124 | | Что | Лицензия | Состояние | Что реально даёт | |
| 125 | |---|---|---|---| |
| 126 | | [`egs-api`](https://crates.io/crates/egs-api) 0.14 | MIT | один сопровождающий, ноль зависимых крейтов, последняя активность февраль 2026 | авторизация, библиотека, **разбор двоичного и JSON манифеста**, разбор чанка, построение адреса чанка. Загрузчика нет | |
| 127 | | `egdata-manifests-parser` 0.1.1 | MIT | два релиза в один день 2025 года, дальше тишина | только разбор | |
| 128 | | `thoo0224/epic_manifest_parser` | MIT | заброшен с 2022 | только разбор, `.unwrap()` россыпью | |
| 129 | | Epic-Asset-Manager (`asset.rs`) | GPL-3 | живой | **есть настоящая загрузка**, но вросшая в GTK4: `set_property`, `emit_by_name`, глобальный атомик. Как зависимость не берётся, как образец алгоритма — годится | |
| 130 | |
| 131 | То есть готовое покрывает **левую колонку таблицы** из начала документа — |
| 132 | ровно ту часть, которая и так безопасна и проверяема. Правая колонка, где |
| 133 | весь риск, в виде библиотеки на Rust не существует ни у кого. |
| 134 | |
| 135 | `egs-api` рассматривался всерьёз как зависимость и не взят по трём |
| 136 | причинам, каждая из которых по отдельности не решающая, а вместе — |
| 137 | достаточная: он тянет собственную реализацию авторизации и библиотеки, |
| 138 | которые в `chl-epic` уже написаны и работают на живом аккаунте (256 игр, |
| 139 | см. комментарии в `library.rs`); у него ноль публичных зависимых крейтов и |
| 140 | один сопровождающий, то есть «вендорить рано или поздно придётся»; и он |
| 141 | MIT — влить его в GPL-3 проект можно, но обратной дороги нет, а свой |
| 142 | разбор оказался куском на 700 строк, который проверяется чужим |
| 143 | кодировщиком насквозь (см. ниже). При другом раскладе — если бы разбор был |
| 144 | на три тысячи строк — вывод был бы противоположный. |
| 145 | |
| 146 | ## legendary как внешний загрузчик: проверено вживую |
| 147 | |
| 148 | Это главная развилка, и она заслуживает не отмашки, а замера. Проверено не |
| 149 | по документации, а установкой в одноразовый venv (никаких изменений в |
| 150 | системе): |
| 151 | |
| 152 | ``` |
| 153 | legendary version "0.21.0", codename "Lowlife" |
| 154 | ``` |
| 155 | |
| 156 | Что выяснилось: |
| 157 | |
| 158 | - **Ставится тривиально.** Чистый Python с PyPI, 1.4 МиБ самого пакета. |
| 159 | В AUR есть готовый `legendary 0.21.0-3`. Но транзитивно он тянет |
| 160 | `requests`/`urllib3`/`certifi` и, главное, `pycryptodomex` — а это уже |
| 161 | собираемый пакет с бинарными модулями, не «просто скрипты». |
| 162 | - **Управляется без диалогов.** `-y` глобальным флагом, |
| 163 | `legendary install <AppName> --base-path <путь> --skip-sdl --max-workers N`. |
| 164 | Флагов действительно много и они закрывают всё, что нужно взрослому |
| 165 | лаунчеру: `--repair`, `--update-only`, `--download-only`, `--platform`, |
| 166 | `--install-tag`, `--prefix`/`--exclude`, `--ignore-free-space`, |
| 167 | `--disable-delta-manifests`, и даже `--manifest <uri>` — подсунуть свой |
| 168 | манифест вместо CDN-ного (то есть откатить игру на старую версию). |
| 169 | - **Состояние можно разделить с Heroic.** Путь конфига берётся из |
| 170 | `LEGENDARY_CONFIG_PATH`, и если направить его в |
| 171 | `~/.config/heroic/legendaryConfig/legendary`, legendary читает и пишет |
| 172 | ровно тот `installed.json`, который `chl_epic::installed` уже разбирает. |
| 173 | Так делает сам Heroic. `user.json` пишется под файловой блокировкой — |
| 174 | параллельный запуск с Heroic это учитывает. |
| 175 | - **Запросы отдают JSON.** `status --json`, `list --json`, |
| 176 | `list-installed --json`, `info <app> --json` — проверено, работает даже |
| 177 | без входа в аккаунт. |
| 178 | - **А вот прогресс установки машиночитаемым не отдаётся.** Это |
| 179 | единственное слабое место, и оно подтверждено чтением исходника |
| 180 | (`downloader/mp/manager.py:762`): прогресс идёт через `logging` обычным |
| 181 | человеческим текстом, |
| 182 | |
| 183 | ``` |
| 184 | = Progress: 12.34% (1234/10000), Running for 00:01:23, ETA: 00:09:00 |
| 185 | - Downloaded: 512.00 MiB, Written: 480.00 MiB |
| 186 | + Download - 12.34 MiB/s (raw) / 20.00 MiB/s (decompressed) |
| 187 | ``` |
| 188 | |
| 189 | и разбирать его пришлось бы регулярным выражением. Внутри у legendary |
| 190 | есть аккуратный `UIUpdate` со всеми числами, но он доступен только если |
| 191 | дёргать `DLManager` как библиотеку из Python, а не через CLI. Heroic |
| 192 | делает именно то, о чём речь, — ловит строку `= Progress:` регуляркой. |
| 193 | |
| 194 | ## Рекомендация |
| 195 | |
| 196 | **Разбор манифеста — свой, нативный. Саму загрузку — через legendary, |
| 197 | внешним процессом.** Не как компромисс «пополам», а потому что у двух |
| 198 | половин задачи разная цена ошибки и разная проверяемость, и правильный |
| 199 | ответ для них разный. |
| 200 | |
| 201 | **Почему загрузка — не своя.** Три довода, по убыванию веса: |
| 202 | |
| 203 | 1. **Цена ошибки — испорченная игра, и проверить её здесь нечем.** Своя |
| 204 | сборка файлов из чанков — это код, который пишет гигабайты по |
| 205 | вычисленным смещениям. Убедиться, что он прав, можно только скачав |
| 206 | настоящую игру настоящим трафиком на настоящем аккаунте; синтетика |
| 207 | этого не даст. У legendary за спиной годы такой проверки на чужих |
| 208 | машинах. Это тот же довод, по которому `CAS-DESIGN.md` отказался |
| 209 | переписывать `restore()` заодно с CAS: «код, ошибка в котором теряет |
| 210 | данные», трогают отдельным проходом, а не попутно. |
| 211 | 2. **Своя загрузка создаёт второго хозяина у чужого состояния.** |
| 212 | `installed.rs` уже написан с прямой оговоркой: файл только читается, |
| 213 | «чужое состояние мы не трогаем, иначе Heroic и Chimera начали бы |
| 214 | спорить, кто из них прав». Нативная установка обязана где-то записать, |
| 215 | что игра установлена и какой она версии. Либо она пишет в |
| 216 | `installed.json` legendary — и тогда мы стали вторым писателем в чужой |
| 217 | формат со своей семантикой; либо заводит своё состояние — и тогда одна |
| 218 | и та же игра существует в двух реестрах, которые расходятся при первом |
| 219 | же обновлении через Heroic. Обе развилки плохие, а через legendary |
| 220 | вопрос не возникает: хозяин один, и он тот же, что был. |
| 221 | 3. **Объём того, что придётся написать заново, больше, чем кажется.** |
| 222 | Скачать чанки и склеить файлы — это ещё не установка. Дальше идут: |
| 223 | докачка с обрыва, ремонт повреждённой установки, дельта-манифесты для |
| 224 | обновлений (без них любое обновление качает игру целиком), метки SDL |
| 225 | для необязательных языков и текстур, предварительная проверка места на |
| 226 | диске, запуск prerequisite-инсталляторов, бюджет разделяемой памяти под |
| 227 | чанки. Всё это в legendary есть флагами, проверено полем и достаётся |
| 228 | бесплатно. |
| 229 | |
| 230 | **Почему разбор — всё-таки свой, а не тоже через legendary.** Потому что |
| 231 | он ничего не стоит и много даёт. Имея манифест на руках, лаунчер до |
| 232 | всякой установки может честно сказать: сколько весит игра, сколько |
| 233 | придётся скачать (не одно и то же — чанк, нужный двум файлам, качается |
| 234 | один раз), какие есть необязательные части, какой файл запускать. Гонять |
| 235 | ради этого внешний процесс и разбирать его человеческий вывод — хуже во |
| 236 | всех отношениях. И это единственная половина, которую можно написать и |
| 237 | доказать без аккаунта Epic. |
| 238 | |
| 239 | **Это расходится с ADR-005 в том, как он написан.** Там сказано: |
| 240 | «Библиотека, установка и запуск — нативно». Библиотека и запуск — |
| 241 | нативные и работают. Установка по этому документу — нет, и это осознанное |
| 242 | предложение изменить решение, а не забывчивость. Довод ADR-005 против |
| 243 | Windows-лаунчера Epic («CEF-браузер внутри Wine, тяжёлый и медленный») |
| 244 | к legendary не относится вообще: это не браузер, не Wine, и работает он |
| 245 | ровно столько, сколько идёт скачивание. Довод «две технологии вместо |
| 246 | одной» — относится, и это настоящая цена: Python в зависимостях у Rust- |
| 247 | лаунчера, который затевался как замена питоновскому StartWine. Именно |
| 248 | поэтому решение за владельцем, а не за этим документом. |
| 249 | |
| 250 | **Запасной вариант, если Python в зависимостях неприемлем принципиально.** |
| 251 | Тогда путь такой: разбор манифеста уже есть (ниже), следом пишется |
| 252 | загрузчик, и **первой целью для него берётся не игра, а сборка Wine** — |
| 253 | то есть данные, которые в любой момент можно перекачать заново, и ошибка |
| 254 | в которых ничего не теряет. Ровно тот же приём сужения scope, которым |
| 255 | `CAS-DESIGN.md` вывел CAS из «опасно» в «сделано». Только после того, как |
| 256 | конвейер отработал на них, он подпускается к играм. |
| 257 | |
| 258 | ## Как это устроено, если делать через legendary |
| 259 | |
| 260 | Слой в `chl-epic`, отдельным модулем, по образцу того, как |
| 261 | `chl_wine::install` уже отдаёт прогресс замыканием: |
| 262 | |
| 263 | ```rust |
| 264 | pub enum Progress { |
| 265 | Preparing, // манифест получен, считаем |
| 266 | Downloading { done: u64, total: u64, bps: u64 }, |
| 267 | Verifying, |
| 268 | Done { path: PathBuf }, |
| 269 | } |
| 270 | ``` |
| 271 | |
| 272 | - Процесс запускается с `LEGENDARY_CONFIG_PATH`, направленным в тот же |
| 273 | каталог, что уже читает `installed::scan()` — чтобы установленная игра |
| 274 | появилась в библиотеке лаунчера сама, без второго реестра. |
| 275 | - Прогресс — построчное чтение stderr и регулярка по `= Progress:`. |
| 276 | Строка, которая не разобралась, **не ошибка**: прогресс-бар просто не |
| 277 | двигается, установка продолжается. Ломать установку из-за того, что в |
| 278 | новой версии legendary поменяли формат лога, было бы худшим из |
| 279 | возможных решений. |
| 280 | - Отсутствие legendary в системе — не паника при запуске лаунчера, а |
| 281 | проверка в `chl-doctor` рядом с существующими: «Epic: скачивание игр |
| 282 | требует legendary, поставь `legendary` из AUR». Всё остальное в разделе |
| 283 | Epic (библиотека, магазин, запуск уже установленного) обязано работать |
| 284 | и без него. |
| 285 | - Отмена — сигнал процессу, а не убийство: legendary при аккуратном |
| 286 | завершении оставляет файл докачки, и следующий запуск продолжит с того |
| 287 | же места. |
| 288 | |
| 289 | Чего в этом слое быть не должно: разбора `installed.json` на запись, |
| 290 | собственного реестра установленных игр Epic и попыток «помочь» legendary, |
| 291 | дописав что-то в его каталог. |
| 292 | |
| 293 | ## Как это устроено, если делать нативно |
| 294 | |
| 295 | Записано не как план к исполнению, а чтобы объём был виден целиком — |
| 296 | именно он и есть главный довод в пользу предыдущего раздела. |
| 297 | |
| 298 | 1. **Получение манифеста.** `GET .../launcher/api/public/assets/v2/platform/ |
| 299 | Windows/namespace/{ns}/catalogItem/{id}/app/{app}/label/Live` с токеном |
| 300 | аккаунта. В ответе — список манифестов, у каждого свой `uri` и |
| 301 | `queryParams` с одноразовым токеном (`f_token`/`cf_token`). Базовый |
| 302 | адрес CDN — тот же `uri` без последнего сегмента. Разбор ответа |
| 303 | тривиален, но токен одноразовый и живёт недолго — планировать это надо |
| 304 | с самого начала, иначе длинная закачка обрывается на середине. |
| 305 | 2. **Планирование.** По манифесту: множество нужных чанков (уникальных, |
| 306 | не по числу файлов), суммарный объём скачивания, объём на диске, |
| 307 | сравнение с уже установленным по sha1 файлов — то, что legendary |
| 308 | называет `check_diff_files`. Проверка свободного места до начала, а не |
| 309 | после. |
| 310 | 3. **Загрузка.** Пул задач: чанк → `GET {base}/{путь чанка}` → проверка |
| 311 | заголовка чанка → zlib → сверка катящегося хэша и sha1 с тем, что |
| 312 | обещал манифест. Непрошедший проверку чанк перекачивается, при |
| 313 | повторе — с другого адреса CDN, если он есть. |
| 314 | 4. **Сборка.** Чанк держится в памяти ровно столько, сколько нужно всем |
| 315 | файлам, которым он отдаёт куски, и освобождается сразу после. Это |
| 316 | единственная нетривиальная часть планирования: наивная схема «скачать |
| 317 | всё, потом собрать» требует места под всю игру дважды. У legendary под |
| 318 | это отдельный бюджет разделяемой памяти (по умолчанию 1 ГиБ) и |
| 319 | необязательная переупорядочивающая оптимизация. |
| 320 | 5. **Запись.** Файл собирается во временное имя и переименовывается |
| 321 | готовым — тот же приём, что уже применяют `snapshot::create()`, |
| 322 | `cas::adopt()` и `chl_core::paths::write_atomically`. Флаг |
| 323 | исполняемости из манифеста ставится при переименовании; симлинки |
| 324 | создаются из `symlink_target`, а не скачиваются. |
| 325 | 6. **Докачка.** Список законченных файлов дописывается по мере готовности; |
| 326 | при повторном запуске законченное пропускается. У legendary это простой |
| 327 | текстовый файл, и простота здесь — достоинство. |
| 328 | |
| 329 | **Требования к безопасности разбора — не пожелание, а планка.** Манифест |
| 330 | приходит из сети, и все длины, счётчики и размеры в нём — числа, которые |
| 331 | нам прислали. Что из этого следует, перечислено в шапке `manifest.rs` и |
| 332 | реализовано: ни одного `unsafe`, ни одного среза по невыверенному индексу, |
| 333 | никогда `Vec::with_capacity` от присланного счётчика (четыре миллиарда |
| 334 | «элементов» — это запрос сотни гигабайт раньше, чем прочитан первый байт), |
| 335 | потолок на распаковку против zip-бомбы, сверка sha1 до разбора тела. Это |
| 336 | тот код, который стоит однажды прогнать фаззером, и он написан так, чтобы |
| 337 | фаззер нашёл ошибку логики, а не панику. |
| 338 | |
| 339 | **Про параллель с `chl_wine::cas` — она есть, но не та, о которой думаешь.** |
| 340 | Соблазн сказать «у Epic контентно-адресуемое хранилище, и у нас тоже, |
| 341 | значит это одно и то же» надо погасить сразу, потому что шаг у них разный: |
| 342 | |
| 343 | - CAS в этом проекте адресует **файл целиком по sha256**, и |
| 344 | `CAS-DESIGN.md` выбрал это осознанно, отвергнув нарезку на чанки: все |
| 345 | найденные на реальной установке дубли были побайтово одинаковыми |
| 346 | файлами, а не «похожими с парой изменённых байт». |
| 347 | - У Epic же чанк — это **окно фиксированного размера в 1 МиБ**, и |
| 348 | адресуется он **GUID, а не хэшем содержимого**; хэш и sha1 нужны для |
| 349 | проверки, а не для адресации. Это нарезка ради экономии трафика при |
| 350 | обновлении, а не ради дедупликации на диске. |
| 351 | |
| 352 | Где они всё-таки встречаются — после установки, а не во время. Скачанная |
| 353 | игра это дерево обычных файлов, и `cas::adopt` на него ложится ровно так |
| 354 | же, как на сборку Wine: две игры на одном движке или две версии одной игры |
| 355 | дадут ту же экономию, что дали Gecko и Mono в сборках Proton. Но это |
| 356 | отдельный шаг после установки, и `CAS-DESIGN.md` прямо предупреждает, что |
| 357 | расширение CAS на новую ось — отдельно согласуемое решение, а не |
| 358 | следствие. |
| 359 | |
| 360 | ## Честная оценка объёма |
| 361 | |
| 362 | Не «несколько дней». По частям: |
| 363 | |
| 364 | | Часть | Оценка | Чем меряно | |
| 365 | |---|---|---| |
| 366 | | Разбор двоичного манифеста | **сделано в этом проходе** | ~1200 строк с тестами, один проход | |
| 367 | | Разбор JSON-манифеста | 1 день | ~140 строк в legendary, но нет эталона для проверки | |
| 368 | | Слой поверх legendary (запуск, прогресс, отмена, doctor, GUI) | **2–4 дня** | новый код небольшой, но нужна живая проверка на настоящей установке | |
| 369 | | Нативно: получение манифеста и планирование | 2–3 дня | ~200 строк в legendary плюс работа с одноразовым токеном | |
| 370 | | Нативно: загрузка, проверка, сборка, бюджет памяти | **1.5–3 недели** | ~1600 строк в legendary, и это та часть, которую надо проверять на настоящих играх, а не на тестах | |
| 371 | | Нативно: докачка, ремонт, дельта-обновления, метки SDL | ещё 1–2 недели | в legendary это отдельные подсистемы, а не флаги | |
| 372 | | Нативно: шифрованные манифесты версии 22+ | неизвестно | не на чем проверить сейчас | |
| 373 | |
| 374 | То есть: **через legendary — считанные дни до работающей установки; |
| 375 | нативно — месяц-полтора до состояния, которому можно доверить чужую |
| 376 | библиотеку игр**, и большая часть этого срока уходит не на написание, а на |
| 377 | проверку того, что нельзя проверить синтетикой. Аудит был прав, назвав это |
| 378 | крупнейшим пробелом. |
| 379 | |
| 380 | ## Что сделано в этом проходе, а что осталось текстом |
| 381 | |
| 382 | **Сделано:** `chl_epic::manifest` — полный разбор двоичного манифеста |
| 383 | Epic. Только чтение: принимает буфер, возвращает структуры, не ходит в |
| 384 | сеть и не пишет на диск. Разбирает заголовок, распаковку с проверкой sha1, |
| 385 | все четыре секции, обе версии `ManifestMeta` и все три версии |
| 386 | `FileManifestList`; выводит идентификатор сборки, номер группы чанка и имя |
| 387 | файла чанка на CDN; считает объём установки и объём скачивания по |
| 388 | уникальным чанкам. Отдельно реализован и проверен катящийся хэш Epic — он |
| 389 | понадобится для проверки скачанных чанков, и сверить его с чужой |
| 390 | реализацией дешевле сейчас, чем отлаживать потом внутри загрузчика, где |
| 391 | ошибка выглядит как «чанк не проходит проверку» без объяснения причины. |
| 392 | 21 тест, `cargo clippy` без предупреждений. |
| 393 | |
| 394 | **Чем это проверено — и почему проверке можно верить.** Эталонный манифест |
| 395 | собран **чужим кодировщиком**: генератор |
| 396 | (`tests/fixtures/make_fixture.py`) импортирует `sw_dlm.py` из референсной |
| 397 | установки StartWine (только на чтение) и просит **legendary** записать |
| 398 | манифест с нарочно неудобным содержимым — `data_version 2`, |
| 399 | `FileManifestList` версии 2, имя файла с кириллицей (то есть UTF-16 строка |
| 400 | с отрицательной длиной), симлинк, метки установки, файл из кусков двух |
| 401 | разных чанков, дополнительные поля. Ожидаемые значения тоже сняты **чужим |
| 402 | разбором с уже записанных байт**, а не взяты из того, что генератор |
| 403 | собирался записать. Поэтому тест сверяет две независимые реализации |
| 404 | формата, а не нашу с самой собой — включая имя файла чанка на CDN, номер |
| 405 | группы, накопленное смещение части внутри файла и идентификатор сборки. |
| 406 | Оба варианта заголовка (сжатый и нет) проверяются отдельно. Плюс проверки |
| 407 | на устойчивость: разбор каждого из 821 возможных обрывов манифеста не |
| 408 | должен паниковать, испорченный байт обязан ловиться контрольной суммой, |
| 409 | завышенный счётчик элементов — отвергаться до всякой аллокации. |
| 410 | |
| 411 | **Не сделано, осталось текстом:** сама загрузка в любом из двух видов, |
| 412 | получение манифеста с серверов Epic, разбор JSON-варианта, расшифровка |
| 413 | манифестов версии 22+. Ничего из этого не написано намеренно: выбор между |
| 414 | внешним загрузчиком и своим меняет всё остальное, а он за владельцем. |
| 415 | Писать конвейер до этого решения означало бы либо выкинуть его, либо |
| 416 | защищать выбор, сделанный по инерции. |
| 417 | |
| 418 | ## Рекомендация к обсуждению |
| 419 | |
| 420 | Как и с `CAS-DESIGN.md`, **разумный следующий шаг — не «начинай писать |
| 421 | загрузчик», а согласовать развилку**. Вопрос владельцу ровно один и он |
| 422 | формулируется коротко: |
| 423 | |
| 424 | > Допустим ли `legendary` внешней зависимостью для скачивания игр Epic — |
| 425 | > так же, как Heroic и Rare делают это годами, — если взамен установка |
| 426 | > заработает за считанные дни, а не через месяц-полтора, и если чужой |
| 427 | > `installed.json` останется с одним хозяином? |
| 428 | |
| 429 | Если да — следующий проход пишет тонкий слой поверх процесса и закрывает |
| 430 | пункт фазы 3 целиком, а `manifest.rs` работает на предварительный расчёт в |
| 431 | интерфейсе. Если нет — ADR-005 остаётся как есть, и следующий проход |
| 432 | начинает нативный загрузчик, но **с чанков сборок Wine, а не с игр**, по |
| 433 | той же логике сужения scope, которая сработала для CAS. |
| 434 | |
| 435 | ## Как перепроверить |
| 436 | |
| 437 | ```bash |
| 438 | cd ~/Projects/chimera-launcher/code |
| 439 | cargo test -p chl-epic # 41 тест, из них 21 про манифест |
| 440 | cargo clippy -p chl-epic --all-targets # без предупреждений |
| 441 | |
| 442 | # Эталон пересобирается чужим кодировщиком (StartWine только на чтение): |
| 443 | PYTHONPATH=~/Games/StartWine/data/scripts \ |
| 444 | python3 crates/chl-epic/tests/fixtures/make_fixture.py \ |
| 445 | crates/chl-epic/tests/fixtures |
| 446 | |
| 447 | # Форма формата — по исходнику legendary, а не по пересказу: |
| 448 | grep -n "header_magic\|def read\b" ~/Games/StartWine/data/scripts/sw_dlm.py |
| 449 | |
| 450 | # Откуда берётся манифест на живом аккаунте: |
| 451 | grep -n "assets/v2/platform" ~/Games/StartWine/data/scripts/sw_func.py |
| 452 | |
| 453 | # Проверка legendary без изменений в системе (одноразовый venv): |
| 454 | python3 -m venv /tmp/lgd && /tmp/lgd/bin/pip install legendary-gl |
| 455 | /tmp/lgd/bin/legendary --version |
| 456 | LEGENDARY_CONFIG_PATH=/tmp/lgd-config /tmp/lgd/bin/legendary status --json |
| 457 | /tmp/lgd/bin/legendary install --help |
| 458 | grep -n "= Progress:" /tmp/lgd/lib/python*/site-packages/legendary/downloader/mp/manager.py |
| 459 | ``` |
| 460 |