suture

Suture — Java 21 библиотека и CLI для создания устойчивых бинарных дельта-патчей.

Обычный бинарный патч часто привязан к конкретным смещениям или строго к одной контрольной сумме исходника. Стоит вставить несколько байтов в начало файла, переупаковать контейнер либо слегка повредить базовую копию — и патч становится неприменимым.

Suture адресует неизменившиеся блоки по содержимому, а не по позиции:

1. source и target делятся на блоки content-defined chunking;
2. совпавшие блоки записываются как ссылки SHA-256 + 16-байтовый якорь;
3. новые данные сохраняются сжатыми литералами;
4. COPY-блоки объединяются в XOR-паритетные группы;
5. весь патч защищается отдельной SHA-256 контрольной суммой;
6. после применения проверяются длина и SHA-256 целевого файла.

В результате один и тот же патч можно применить не только к точному source, но и к базе, где блоки были сдвинуты. Кроме того, Suture восстанавливает один отсутствующий COPY-блок в каждой паритетной группе.

Где это применимо

• доставка обновлений больших бинарных файлов;
• обновление VM-образов, архивов, моделей и игровых ресурсов;
• патчи для файлов, которые могли быть перепакованы или получить префикс/суффикс;
• передача изменений по нестабильным каналам;
• миграции, где исходные копии могут иметь локальные повреждения;
• резервные цепочки, которым нужна частичная самовосстанавливаемость.

Быстрый старт

Требуется Java 21 или новее.

Linux / macOS

./suture help
./suture create old.bin new.bin update.sut
./suture verify old.bin update.sut
./suture apply old.bin update.sut restored.bin

Windows

suture.bat help
suture.bat create old.bin new.bin update.sut
suture.bat verify old.bin update.sut
suture.bat apply old.bin update.sut restored.bin

Либо напрямую:

java -jar dist/suture.jar create old.bin new.bin update.sut

Команды

Создание патча

suture create [options] SOURCE TARGET PATCH

--min SIZE       минимальный блок, по умолчанию 2KiB
--avg SIZE       средний блок, степень двойки, по умолчанию 8KiB
--max SIZE       максимальный блок, по умолчанию 64KiB
--parity N|off   количество COPY-блоков в XOR-группе, по умолчанию 8

Пример с более крупными блоками:

./suture create --min 8KiB --avg 32KiB --max 256KiB --parity 12 old.img new.img update.sut

Чем меньше блоки, тем лучше распознаются небольшие изменения, но тем больше служебных данных. Паритет группы из N блоков допускает потерю одного блока и обычно добавляет примерно 1/N от объёма COPY-части до сжатия.

Проверка применимости

./suture verify candidate-base.bin update.sut

Команда полностью реконструирует результат в памяти, проверяет контрольную сумму, но не записывает выходной файл.

Применение

./suture apply candidate-base.bin update.sut result.bin

Выход создаётся через временный файл и атомарное переименование, когда файловая система это поддерживает.

Инспекция

./suture inspect update.sut
./suture inspect --json update.sut

Почему патч переживает сдвиги

Suture сначала пытается найти требуемый блок среди CDC-блоков новой базы. Если границы изменились из-за вставки или удаления, используется второй путь: поиск 16-байтового якоря по всему файлу с последующей проверкой полного SHA-256 блока. Поэтому исходные байты могут находиться по другому смещению и даже внутри иначе нарезанного участка.

Что именно восстанавливает паритет

Для каждой группы COPY-блоков сохраняется побайтовый XOR, дополненный нулями до длины самого длинного блока. Если ровно один блок отсутствует, он вычисляется как:

missing = parity XOR block1 XOR block2 XOR ... XOR blockN

Восстановленный блок обязательно проходит проверку SHA-256. При потере двух и более блоков в одной группе Suture завершает работу с кодом 3 и перечисляет недостающие хэши, не создавая ложный результат.

Использование как библиотеки

import dev.suture.CreateOptions;
import dev.suture.PatchInfo;
import dev.suture.Suture;

import java.nio.file.Path;

public final class Example {
    public static void main(String[] args) throws Exception {
        PatchInfo info = Suture.create(
                Path.of("old.bin"),
                Path.of("new.bin"),
                Path.of("update.sut"),
                CreateOptions.DEFAULT);

        Suture.verify(Path.of("candidate.bin"), Path.of("update.sut"));
        Suture.apply(Path.of("candidate.bin"), Path.of("update.sut"), Path.of("result.bin"));

        System.out.println(info.copyRatio());
    }
}

Публичный API:

• Suture.create(...)
• Suture.inspect(...)
• Suture.verify(...)
• Suture.apply(...)
• ChunkingConfig
• CreateOptions
• PatchInfo
• ApplyReport
• MissingChunksException

Сборка

Linux / macOS

./build.sh
./test.sh

Windows

build.bat

Проект не использует Maven, Gradle и сторонние зависимости. Нужен только JDK 21.

Тесты

test.sh проверяет:

• пустой target;
• обычный round-trip;
• применение к базе со сдвинутыми блоками;
• восстановление одного отсутствующего блока XOR-паритетом;
• отказ при двух отсутствующих блоках в одной группе;
• обнаружение повреждённого патча;
• побайтовую детерминированность патча.

Гарантии формата

• SHA-256 для source, target, каждого COPY-блока и всего патча;
• строгая проверка всех длин, типов операций и групп паритета;
• отказ при неизвестной версии формата;
• детерминированное построение патча;
• отсутствие частично записанного целевого файла;
• отсутствие внешних зависимостей и сетевых обращений.

Практические пределы

Текущая законченная реализация намеренно работает с файлами целиком в памяти и поддерживает target до приблизительно 2 ГиБ. Это упрощает верификацию, делает библиотеку независимой от платформы и исключает промежуточные недостоверные результаты. Для крупных файлов выбирайте размер JVM heap с запасом относительно source, target и patch.

Структура

src/main/java/dev/suture/          публичный API
src/main/java/dev/suture/internal/ формат, CDC, патчинг и восстановление
src/main/java/dev/suture/cli/      CLI
src/test/java/                     автономные тесты
examples/                          демонстрационный сценарий
FORMAT.md                          спецификация бинарного формата

Лицензия

MIT.

Исходный код · MIT