# Wasm Encoding Tool

![Static Badge](https://img.shields.io/badge/Powered%20by-csasq-blue)
![Static Badge](https://img.shields.io/badge/Python-3.9%2B-blue)
![Static Badge](https://img.shields.io/badge/License-CC%20BY--NC%204.0-blue)

Утилита для сжатия файлов WebAssembly (Wasm) с использованием наиболее распространенных кодировок, поддерживаемых браузерами. Данный подход позволяет заранее подготовить сжатые файлы для отдачи их веб-сервером.

## Преимущества

Ниже приведено сравнение размера Wasm без сжатия и с применением максимального уровня сжатия каждым из поддерживаемых алгоритмов.

Размер исходного файла Wasm — 8.0M.

| Алгоритм сжатия | Размер | Коэффициент сжатия | Степень сжатия |
|-----------------|-------:|-------------------:|---------------:|
| Brotli          |   2.5M |                3.2 |         68.75% |
| Zstandard       |   2.6M |               3.08 |          67.5% |
| Gzip            |   3.1M |               2.58 |         61.25% |
| Deflate         |   3.1M |               2.58 |         61.25% |

Как следует из таблицы, в лучшем случае сжатый файл имеет размер приблизительно в 3,2 раза меньше, чем исходный.

## Рекомендации

1. Следите за пересечением относительных путей, если меняете предустановленные значения конфигурации.
2. Протестируйте работу утилиты с различным количеством параллельных потоков. Зачастую, вы можете запускать сжатие с неограниченно большим значением параметра `max_threads`. В лучшем случае получится добиться сжатия каждого файла каждым алгоритмом в отдельном потоке. В худшем случае процесс будет убит средствами OOM Killer.

## Конфигурация

Файл конфигурации следует расположить в `./config.ini` относительно рабочей директории утилиты.

Ниже приведен пример конфигурации со всеми возможными разделами и параметрами. Все пути за исключением параметра `Main.base_path` можно указывать как абсолютными, так и относительными.

```ini
[Main]
base_path = /opt/my-project
max_threads = 4
log_level = info

[Input]
path = ./source

[Output]
path = ./public
dir_mode = 755
file_mode = 644

[Output.Wasm.Source]
enabled = true
path = ./wasm/src

[Output.Wasm.Brotli]
enabled = true
path = ./wasm/br
level = 11

[Output.Wasm.Zstandard]
enabled = true
path = ./wasm/zstd
level = 22

[Output.Wasm.Gzip]
enabled = true
path = ./wasm/gzip
level = 9

[Output.Wasm.Deflate]
enabled = true
path = ./wasm/deflate
level = 9

[Output.Other]
enabled = true
path = .

[Backup]
enabled = true
path = ./backup
```

### Раздел `Main`

Содержит основные параметры утилиты.

- `base_path` — базовый путь для построения относительных путей;
- `max_threads` — максимальное количество параллельных потоков;
- `log_level` — уровень логирования (`critical`, `fatal`, `error`, `warn`, `warning`, `info`, `debug`, `notset`).

### Раздел `Input`

Содержит параметры входной директории. Относительные пути строятся от `Main.base_path`.

- `path` — путь до исходников веб-приложения.

### Раздел `Output`

Содержит параметры выходной директории. Относительные пути строятся от `Main.base_path`.

- `path` — путь до исходников веб-приложения после сжатия;
- `dir_mode` — режим доступа к директориям;
- `file_mode` — режим доступа файлам.

### Раздел `Output.Wasm.Source`

Содержит параметры копирования исходников Wasm. Относительные пути строятся от `Output.path`.

- `enabled` — включить копирование исходников Wasm;
- `path` — путь до исходников Wasm.

### Разделы `Output.Wasm.Brotli`, `Output.Wasm.Zstandard`, `Output.Wasm.Gzip`, `Output.Wasm.Deflate`

Содержит параметры сжатия исходников Wasm. Относительные пути строятся от `Output.path`.

- `enabled` — включить сжатие исходников Wasm алгоритмом;
- `path` — путь до сжатых исходников;
- `level` — уровень сжатия:
  - Brotli — с `1` по `11`,
  - Zstandard — с `1` по `22`,
  - Gzip — с `1` по `9`,
  - Deflate — с `1` по `9`.

### Раздел `Output.Other`

Содержит параметры копирования прочих исходников. Относительные пути строятся от `Output.path`.

- `enabled` — включить копирование прочих файлов;
- `path` — путь до прочих файлов.

### Раздел `Backup`

Содержит параметры резервной копии. Относительные пути строятся от `Main.base_path`.

- `enabled` — включить создание резервной копии;
- `path` — путь до резервной копии.

## Конфигурация Nginx

Ниже приведен пример конфигурации Nginx для корректной отдачи файлов Wasm с указанием заголовков `Content-Type` и `Content-Length`.

Обратите внимание на порядок элементов в `map $http_accept_encoding $wasm_accept_encoding`. Изменив этот порядок, вы можете повлиять на приоритет применения алгоритмов сжатия.

```nginx
map $http_accept_encoding $wasm_accept_encoding {
    "~br"       "br";
    "~zstd"     "zstd";
    "~gzip"     "gzip";
    "~deflate"  "deflate";
    default     "src";
}

map $wasm_accept_encoding $wasm_content_encoding {
    "br"        "br";
    "zstd"      "zstd";
    "gzip"      "gzip";
    "deflate"   "deflate";
    default     "";
}

root    /opt/my-project/public;

location / {
    try_files       $uri /index.html;
}

location ~* \.wasm$ {
    try_files       /wasm/$wasm_accept_encoding/$uri =404;
    default_type    application/wasm;
    add_header      "Content-Encoding" $wasm_content_encoding;
}
```