# bounce

<p align="center">
  <img src="assets/logo.png" alt="bounce cosmic logo" width="400">
</p>

[![Crates.io](https://img.shields.io/crates/v/nvg-bounce.svg)](https://crates.io/crates/nvg-bounce)
[![CI](https://github.com/infosave2007/bounce/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/infosave2007/bounce/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-Apache%202.0-blue)
![Rust](https://img.shields.io/badge/rust-1.70%2B-orange)

**bounce** — быстрый многопоточный файловый архиватор на чистом Rust без внешних зависимостей. В основе лежит кодек **Big Bounce** с умной динамической маршрутизацией методов сжатия и оптимизированным байт-шаффлингом для крупных бинарных данных. Разработан для обеспечения максимальной скорости работы и безопасности.

## Основные возможности

- **Ноль внешних зависимостей**: Только стандартная библиотека Rust.
- **Кроссплатформенность**: Полная поддержка macOS, Linux и Windows (на архитектурах x86_64, aarch64, x86).
- **Асинхронный конвейер (Pipeline)**: Параллельная работа диска и процессора. Пока с диска читается следующий блок данных, CPU-токи уже распаковывают предыдущий.
- **Smart Routing (Умная маршрутизация)**: Анализирует энтропию файла "на лету" и автоматически выбирает оптимальную стратегию сжатия (LZ77, алгоритм Хаффмана, Byte-Shuffling или прямое копирование).
- **Безопасность**: Защита от атак типа path traversal. Контроль целостности файлов по контрольной сумме CRC-32.
- **Pre-flight проверки диска**: Архиватор заранее проверяет наличие свободного места перед распаковкой или упаковкой, предотвращая сбои из-за нехватки памяти.
- Расширение архивов: **`.bnc`**.

## Основные сценарии использования (Ниши)

`bounce` специально спроектирован для работы с массивными и плотными бинарными файлами, где традиционные архиваторы упираются в узкие горлышки скорости или потребления ОЗУ.

- **Большие языковые модели (LLM) и нейросети**: Идеально подходит для сжатия гигабайтных весов искусственного интеллекта (`.safetensors`, `.gguf`, `.pt`, `.bin`). Алгоритм byte-shuffle математически "выравнивает" `float16`/`float32` структуры, обеспечивая экстремальную скорость распаковки (~1.1 ГБ/с), что критично для пайплайнов быстрой загрузки моделей в память видеокарты.
- **Big Data и научные вычисления (HPC)**: Быстрое архивирование бинарных датасетов, дампов памяти, состояний симуляций и телеметрии, где максимальная пропускная способность I/O (ввода-вывода) диска важнее всего.
- **GameDev и упаковка ассетов**: Мгновенная упаковка и распаковка тяжелых игровых ресурсов (текстур, геометрии, аудио-банков) благодаря асинхронному пулу буферов и полному отсутствию тяжеловесных внешних зависимостей.

## FAQ и Известные ограничения

**Когда НЕ стоит использовать `bounce`?**
Хотя `bounce` отлично справляется со своими задачами, это не "серебряная пуля". Вам лучше использовать традиционные архиваторы (такие как `tar.gz`, `zstd` или `7z`), если:
- **Ваши данные уже сжаты:** Файлы вроде `.mp4`, `.jpg`, `.gz` или `.zip` имеют максимальную энтропию. `bounce` быстро это поймет и просто скопирует их "как есть" (без сжатия), чтобы сэкономить процессорное время, но размер файла не уменьшится.
- **Вы сжимаете огромные текстовые массивы:** Для гигантских исходных кодов или текстовых логов лучше подойдут инструменты с огромными словарями (`zstd --long`, `xz`). В `bounce` размер скользящего окна LZ77 жестко ограничен 64 КБ, чтобы удерживать потребление памяти на нулевом уровне и обеспечивать астрономическую скорость распаковки.
- **Вам нужен максимальный коэффициент сжатия любой ценой:** `bounce` ставит на первое место пропускную способность I/O (скорость), а не выжимание последнего байта.

---

## Установка

### 1. Готовые бинарные файлы (Рекомендуется)
Вы можете скачать готовые скомпилированные версии для macOS, Linux и Windows на странице [GitHub Releases](../../releases). Установка Rust для этого не требуется.

### 2. Через Cargo (crates.io)
Если у вас установлен набор инструментов Rust, вы можете установить `bounce` напрямую из crates.io:
```bash
cargo install nvg-bounce
```
*(Примечание: После установки бинарный файл будет доступен в терминале как `bounce`)*

### 3. Сборка из исходников
Для сборки последней версии из исходного кода:
```bash
git clone https://github.com/infosave2007/bounce.git
cd bounce
cargo build --release
# Исполняемый файл появится по пути target/release/bounce
```

### macOS Apple Silicon (M1/M2/M3/M4)
Для максимальной производительности на Mac с процессорами ARM64 убедитесь, что вы компилируете нативно, а не через эмулятор Rosetta 2:

```bash
cargo build --release --target aarch64-apple-darwin
```

### Установка в систему
```bash
cargo install --path .
```

---

## Использование

```bash
bounce <команда> [опции] <архив> [файлы...]
```

### Команды

| Команда | Алиас | Назначение |
|---------|-------|------------|
| `create`  | `c` | Создать архив из файлов и каталогов |
| `extract` | `x` | Распаковать архив (полностью или выбранные файлы) |
| `list`    | `l` | Показать содержимое архива |
| `test`    | `t` | Проверить целостность архива (CRC-32) |

### Опции

| Опция | Описание |
|-------|----------|
| `-1 ... -N` | Уровень сжатия (по-умолчанию: `-1`). `-1` самый быстрый, `-N` неограниченно масштабируется экспоненциально (например `-10` = окно 32 МБ). |
| `-o, --output <dir>` | Каталог для распаковки (по умолчанию — текущий) |
| `-c, --stdout` | Выводить распакованные файлы напрямую в stdout |
| `-f, --force` | Перезаписывать существующие файлы при распаковке |
| `-v, --verbose` | Показывать детальный прогресс по каждому файлу |
| `-q, --quiet` | Отключить вывод итоговой сводки |

### Пример уровней сжатия

*Влияние уровня сжатия на видеофайл размером 61.7 МБ (`.mp4`):*

| Уровень | Окно / Блок | Сжатый размер | Ratio |
|---------|-------------|---------------|-------|
| `-1` | 64 КБ / 128 КБ | 61.5 MB | 99.7% |
| `-2` | 128 КБ / 128 КБ | 61.4 MB | 99.6% |
| `-3` | 256 КБ / 256 КБ | 61.4 MB | 99.6% |
| `-5` | 1 МБ / 1 МБ | 61.4 MB | 99.6% |
| `-6` | 2 МБ / 2 МБ | 61.4 MB | 99.6% |
| `-7` | 4 МБ / 4 МБ | 61.4 MB | 99.6% |
| `-8` | 8 МБ / 8 МБ | 61.4 MB | 99.6% |
| `-9` | 16 MB / 16 MB | 61.4 MB | 99.6% |
| `-10`| 32 MB / 32 MB | 61.4 MB | 99.6% |

### Примеры

**Упаковать файлы и папки:**
```bash
bounce c backup.bnc report.pdf photos/
```

**Распаковать архив в конкретную папку:**
```bash
bounce x backup.bnc -o restored/
```

**Посмотреть содержимое архива:**
```bash
bounce l backup.bnc
```

**Проверить целостность архива:**
```bash
bounce t backup.bnc
```

---

## Архитектура и алгоритмы

`bounce` использует DEFLATE-подобный алгоритм, усиленный механизмами динамической реструктуризации и агрессивной многопоточности:

1. **Smart Routing (Предварительный анализ)**
   Перед сжатием файла `bounce` вычисляет его информационную энтропию Шеннона, битовую плотность и частоту повторов. На базе этого профиля выбирается идеальный вычислительный конвейер (включение/отключение LZ77, включение Byte-Shuffle). Это экономит ресурсы процессора на несжимаемых данных.

2. **Byte-Shuffling для структурных данных**
   Для бинарных массивов (например, веса нейросетей в формате `float32` или `float16`), кодек применяет транспонирование байтов (stride = 2 или 4). Это выравнивает мантиссы и экспоненты чисел друг с другом, обнажая колоссальную структурную избыточность для энтропийного кодирования.

3. **Блочная многопоточность**
   Крупные файлы автоматически разбиваются на независимые блоки (chunks), что позволяет утилизировать все ядра процессора при сжатии и распаковке.

4. **Асинхронный конвейер (Pipeline)**
   Ядро распаковки работает в режиме конвейера с пулом буферов (Buffer Pool): фоновый поток последовательно читает данные с диска, декодирует их параллельно, и по внутренним zero-copy каналам передает главному потоку для проверки CRC и мгновенной записи. Жесткий диск и процессор работают одновременно.

> **Ограничение словаря:** Ради максимальной скорости и минимального потребления оперативной памяти, размер окна поиска LZ77 ограничен 64 КБ. `bounce` феноменально сжимает плотные бинарные файлы и локальные повторы, но на текстовых базах данных может уступать алгоритмам с большими словарями (`zstd`, `xz`).

---

## Бенчмарки

Сравнение с распространенными архиваторами на **Apple MacBook Air M4 (10 ядер, 24 ГБ RAM, arm64)**.
Для запуска локальных бенчмарков используйте: `bash benchmark.sh`

### Текст / XML (enwik8) — 95.4 МБ (`enwik8`)
*100 миллионов байт XML-текста английской Википедии.*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -2** | **34.6 MB** | **36.2%** | **189.1 MB/s** | **988.7 MB/s** |
| zstd -3 | 33.8 MB | 35.4% | 753.3 MB/s | 823.6 MB/s |
| gzip -9 | 34.8 MB | 36.5% | 32.1 MB/s | 653.5 MB/s |
| lz4 -9 | 40.3 MB | 42.3% | 240.9 MB/s | 1210.9 MB/s |
| zstd -19 | 25.7 MB | 26.9% | 5.5 MB/s | 789.3 MB/s |
| bzip2 -9 | 27.7 MB | 29.0% | 22.2 MB/s | 54.9 MB/s |
| brotli -q 11 | 24.5 MB | 25.7% | 0.8 MB/s | 518.3 MB/s |

### Веса моделей (model.safetensors) — 255.5 МБ (`model.safetensors`)
*Неструктурированные веса нейросетей IEEE-754. Этот тест демонстрирует эффективность нашей трансформации `byte_shuffle`.*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -2** | **218.1 MB** | **85.3%** | **179.3 MB/s** | **1071.2 MB/s** |
| zstd -3 | 235.3 MB | 92.1% | 2056.8 MB/s | 1035.1 MB/s |
| gzip -9 | 235.6 MB | 92.2% | 39.2 MB/s | 481.2 MB/s |
| lz4 -9 | 255.5 MB | 100.0% | 381.3 MB/s | 2889.1 MB/s |
| zstd -19 | 235.2 MB | 92.1% | 32.9 MB/s | 1055.0 MB/s |
| bzip2 -9 | 241.5 MB | 94.5% | 15.8 MB/s | 31.9 MB/s |
| brotli -q 5 | 235.1 MB | 92.0% | 195.2 MB/s | 206.5 MB/s |

### Смешанный корпус (silesia.tar) — 202.2 МБ (`silesia.tar`)
*Смешанный корпус данных, содержащий исходный код, тексты книг, бинарные и словарные файлы.*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -2** | **65.4 MB** | **32.3%** | **250.6 MB/s** | **997.7 MB/s** |
| zstd -3 | 63.2 MB | 31.3% | 1337.3 MB/s | 1150.3 MB/s |
| gzip -9 | 64.5 MB | 31.9% | 19.5 MB/s | 896.2 MB/s |
| lz4 -9 | 74.4 MB | 36.8% | 252.7 MB/s | 1848.5 MB/s |
| zstd -19 | 50.4 MB | 24.9% | 13.9 MB/s | 1138.6 MB/s |
| bzip2 -9 | 52.0 MB | 25.7% | 20.8 MB/s | 64.2 MB/s |
| brotli -q 11 | 47.5 MB | 23.5% | 0.8 MB/s | 520.4 MB/s |

### Дамп базы данных (SQL) — 164.3 МБ (`employees.sql`)
*Объединенный, инлайненный SQL-дамп демонстрационной базы данных MySQL, содержащий реальные записи сотрудников.*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -2** | **35.1 MB** | **21.3%** | **166.3 MB/s** | **1190.1 MB/s** |
| zstd -3 | 37.9 MB | 23.1% | 1286.2 MB/s | 935.9 MB/s |
| gzip -9 | 33.2 MB | 20.2% | 7.6 MB/s | 1121.7 MB/s |
| lz4 -9 | 46.9 MB | 28.5% | 108.0 MB/s | 1679.0 MB/s |
| zstd -19 | 18.4 MB | 11.2% | 5.6 MB/s | 1382.4 MB/s |
| bzip2 -9 | 25.5 MB | 15.5% | 24.0 MB/s | 85.0 MB/s |
| brotli -q 11 | 17.1 MB | 10.4% | 0.8 MB/s | 732.1 MB/s |

### Структурированные данные (JSON) — 181.0 МБ (`citylots.json`)
*Большой структурированный JSON-датасет, содержащий географические характеристики земельных участков Сан-Франциско.*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -2** | **19.0 MB** | **10.5%** | **468.4 MB/s** | **1483.1 MB/s** |
| zstd -3 | 17.7 MB | 9.8% | 1916.6 MB/s | 1795.7 MB/s |
| gzip -9 | 21.2 MB | 11.7% | 46.4 MB/s | 1733.4 MB/s |
| lz4 -9 | 23.6 MB | 13.1% | 576.7 MB/s | 2092.8 MB/s |
| zstd -19 | 12.3 MB | 6.8% | 14.4 MB/s | 2124.8 MB/s |
| bzip2 -9 | 17.8 MB | 9.8% | 13.9 MB/s | 103.5 MB/s |
| brotli -q 11 | 11.9 MB | 6.6% | 1.3 MB/s | 1173.3 MB/s |

### Сжатое видео (Fallback-тест) — 61.7 МБ (`video.mp4`)
*Сжатое видео H.264. Уже сжатый файл с высокой энтропией для проверки безопасности/детектирования fallback-режима на максимальном уровне сжатия (-9).*

| Инструмент | Размер | Ratio | C (скорость) | D (скорость) |
|------------|-------:|------:|-------------:|-------------:|
| **bounce -9** | **61.4 MB** | **99.6%** | **178.7 MB/s** | **283.0 MB/s** |
| zstd -3 | 61.6 MB | 99.8% | 932.9 MB/s | 1504.3 MB/s |
| gzip -9 | 61.5 MB | 99.7% | 57.2 MB/s | 721.0 MB/s |
| lz4 -9 | 61.6 MB | 99.9% | 302.7 MB/s | 1274.0 MB/s |
| zstd -19 | 61.2 MB | 99.2% | 14.9 MB/s | 1224.9 MB/s |
| bzip2 -9 | 61.6 MB | 99.9% | 15.2 MB/s | 31.5 MB/s |
| brotli -q 5 | 61.5 MB | 99.8% | 500.7 MB/s | 1329.5 MB/s |

---

## Теория и происхождение названия

Название **bounce** (отскок) и математическая база архитектуры кодека вдохновлены [теорией Вакуум-Материальной Флуктуации (VMF)](https://github.com/infosave2007/vmf) (Null-Vector Gravity).

В космологии "Большой отскок" (Big Bounce) описывает циклическую Вселенную. В отличие от стандартной модели, где коллапс заканчивается сингулярностью, в теории VMF макроскопическое плавление вакуума останавливает сжатие на критической плотности, вызывая отскок. Это описывается модифицированным уравнением Фридмана:

$$ H^2 \propto \rho \left(1 - \frac{\rho}{\rho_c}\right) $$

где критическая плотность математически связана с пропорцией **золотого сечения**: $\rho_c \propto \frac{3 - \sqrt{5}}{2}$.

**Космологический «баунс» как архитектура кодека:**
Алгоритм `bounce` реализует эту физическую модель как обычный вычислительный pipeline: 
- **Коллапс:** Дискретная эволюция длины битстроки "схлопывает" данные, уплотняя их в сверхплотные блоки.
- **Критическая плотность:** Архиватор избегает информационной "сингулярности", останавливая сжатие на критическом пороге энтропии (пропорции золотого сечения диктуют идеальную плотность упаковки).
- **Отскок (Bounce):** Данные полностью и без потерь возвращаются в исходное состояние при мгновенной распаковке.

NVG-баунс служит мощной математической абстракцией: внутри это глубокая космологическая модель эволюции информации, а снаружи — просто сверхбыстрый модуль, который сжимает файлы и безупречно их восстанавливает.

---

## Лицензия и патенты

Распространяется по лицензии **Apache License 2.0** — см. файл [LICENSE](LICENSE).

Динамический механизм маршрутизации задач (Signal Reconstruction Resonance) защищен патентной заявкой в США: **USA 19/452,440 от Jan 19, 2026**. Подробности в файле [NOTICE](NOTICE).

---

## ❤️ Поддержка проекта
Если этот проект оказался вам полезен, вы можете поддержать его развитие через Tribute:

👉 https://t.me/tribute/app?startapp=dzX1

Каждое пожертвование помогает развивать bounce. Спасибо! 🙌
