RUST У WASM, МЕЖА З HOST-СЕРЕДОВИЩЕМ

Вступ: від ручного .wat до компільованого коду

У Лекції 9 ми писали .wat вручну — корисно для розуміння моделі, але непридатно для реальної програми в кілька тисяч рядків. Лекція 10 замикає лінію курсу: замість людини, що вручну розставляє local.get/i32.add, цю роботу виконує компілятор — той самий rustc, яким ми користувалися для нативного x86-64 у Модулях 1–2, тепер спрямований на іншу ціль компіляції. Rust тут — не випадковий вибір: система володіння й запозичень (Лекції 5–7) дає гарантії безпеки пам'яті на етапі компіляції, а це саме те, що потрібно для коду, який піде виконуватися в чужому, потенційно ворожому браузерному host-середовищі (host — рушій, що запускає модуль; сам модуль для нього — guest) без окремого рантайму збирача сміття.

Ціль компіляції wasm32-unknown-unknown

Rust визначає ціль компіляції як триплет (target triple) архітектура-виробник-ОС. Для WASM у браузері використовується wasm32-unknown-unknown:

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown --release

• wasm32 — 32-бітна адресація лінійної пам'яті (специфікація WASM MVP; wasm64 існує, але поки що експериментальний);
• перше unknown — виробник не заданий (нема сенсу для віртуальної машини);
• друге unknown — немає конкретної операційної системи: жодного libc, жодних системних викликів. Це «голий метал» у сенсі відсутності ОС, майже як ціль для мікроконтролера.

Існує і сусідня ціль — wasm32-wasi (нині wasm32-wasip1/wasip2), яка натомість надає POSIX-подібний інтерфейс системних викликів через стандарт WASI (WebAssembly System Interface) — придатна для запуску WASM поза браузером, наприклад у Wasmtime як заміну контейнера. У курсі ми зосереджені на wasm32-unknown-unknown, бо мета — сторінка в браузері, а не автономний бінарник.

wasm-bindgen: що генерується під капотом

Ручний WASM (Лекція 9) обмінюється з хостом лише числами (i32, f64) — це все, що розуміє специфікація WASM. Rust-типи (String, &str, struct, Vec<T>) складніші, і саме тут вступає wasm-bindgen:

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn greet(name: &str) -> String {
    format!("Вітаю, {name}! Ядро на зв'язку.")
}

Атрибут #[wasm_bindgen] — процедурний макрос, який під час компіляції генерує код по обидва боки межі:

• усередині .wasm — додаткові extern "C"-функції, що вміють приймати/повертати «сирі» числові дескриптори замість Rust-типів;
• зовні — JS-файл (glue code), що ховає цю роботу за звичайним, ергономічним викликом функції.

Маршалінг типів через межу

Маршалінг (marshalling) — перетворення значення при перетині межі мов. Складність різна залежно від типу:

Правило, яке варто запам'ятати: чим простіший тип на межі, тим дешевший виклик. Гарячий шлях (функція, яку викликають щокадру в анімації чи грі) варто проєктувати на прості числові типи; складні структури краще передавати одноразово або пакетно.

wasm-pack: конвеєр збірки в один виклик

wasm-pack build --target web

Ця одна команда виконує послідовність, яку інакше довелося б збирати вручну: cargo build --target wasm32-unknown-unknown --release, потім запуск CLI wasm-bindgen для генерації JS-обгортки з метаданих, які компілятор вклав у .wasm, і пакування результату в теку pkg/:

pkg/
├── sid_core_bg.wasm     # сам бінарник
├── sid_core.js           # JS/ES-модуль з експортованими функціями
├── sid_core.d.ts          # типи для TypeScript
└── package.json           # метадані для npm/бандлерів

Прапорець --target web готує ES-модуль, готовий до прямого <script type="module"> без бандлера; --target bundler — варіант для Webpack/Vite; --target nodejs — для CommonJS-середовища Node.js.

Виклик із HTML/JS

<script type="module">
  import init, { greet } from './pkg/sid_core.js';
  await init();                          // підвантажити й інстанціювати .wasm
  document.querySelector('#btn').onclick = () => {
    console.log(greet('С.І.Д.'));
  };
</script>

init() — асинхронна функція: завантажує .wasm по мережі (fetch), компілює й інстанціює модуль (та сама операція WebAssembly.instantiateStreaming, яку ми викликали вручну в Лекції 9), і лише після її завершення greet готова до виклику як звичайна JS-функція.

Пам'ять через межу: хто відповідає за звільнення

Лінійна пам'ять модуля з боку JS видима як instance.exports.memory.buffer — звичайний ArrayBuffer. Rust-об'єкти (struct, обгорнуті #[wasm_bindgen]), передані в JS, насправді залишаються всередині лінійної пам'яті WASM; JS-сторона тримає лише непрозорий дескриптор (вказівник). Оскільки в WASM немає збирача сміття, і Rust звільняє пам'ять детерміновано через Drop лише коли є явний виклик, а не автоматично з боку JS, wasm-bindgen генерує для кожного такого класу метод .free(). Забути викликати .free() на JS-стороні — це витік пам'яті: сам об'єкт живий, доки JS тримає посилання, але навіть після втрати посилання пам'ять у WASM-модулі не звільняється, бо збирач сміття JS не знає нічого про купу (heap) Rust усередині лінійної пам'яті.

Відтворювані збірки (reproducible builds)

Проблема, добре знайома з Модуля 1: «на моїй машині збирається інший .wasm». Причини — різні версії rustc, wasm-bindgen, транзитивних крейтів, навіть різний порядок символів через непослідовну ітерацію HashMap під час кодогенерації. Для системного й безпекового коду це критично: без відтворюваності неможливо довести, що опублікований бінарник відповідає опублікованому вихідному коду — а це саме та властивість, яку перевіряє аудит перед тим, як довірити модулю виконання в браузері користувача.

Практика:

FROM rust:1.82-slim
RUN rustup target add wasm32-unknown-unknown
RUN cargo install wasm-pack --version 0.13.1 --locked
WORKDIR /build
COPY Cargo.toml Cargo.lock ./
COPY src ./src
RUN wasm-pack build --target web --release

• Cargo.lock фіксує точні версії всіх залежностей — команда cargo build --locked відмовляється збирати, якщо Cargo.lock розходиться з Cargo.toml;
• фіксована версія образу (rust:1.82-slim, а не rust:latest) і фіксована версія wasm-pack прибирають дрейф інструментарію;
• збірка всередині контейнера ізолює процес від локального стану машини розробника — той самий принцип ізоляції, що в Модулі 1, тепер працює на гарантію байт-у-байт відтворюваності, а не на безпеку виконання.

Верифікація — тривіальна: sha256sum pkg/*.wasm на двох незалежних машинах має дати однаковий хеш.

Три межі курсу

Весь курс — це послідовне занурення на три різні межі ізоляції та перевірки:

Спільний мотив усіх трьох: ізоляція й перевірка відбуваються якомога раніше — на етапі ядра (namespaces), компілятора (borrow checker) чи завантаження модуля (WASM validation), а не «десь у рантаймі, якщо пощастить».

Підводні камені

• Розсинхронізовані версії wasm-bindgen — версія крейта в Cargo.toml і версія CLI, встановленого глобально, повинні збігатися, інакше збірка падає з незрозумілою помилкою генерації.
• Складний Rust-тип без #[wasm_bindgen] переданий напряму в експортовану сигнатуру — помилка компіляції про те, що тип не реалізує потрібний трейт маршалінгу.
• Забутий .free() для JS-обгорнутих Rust-структур — тихий витік пам'яті лінійної області, який не покаже жоден JS-профайлер (адже сам JS-об'єкт малий, «важка» пам'ять прихована в .wasm-хіпі).
• file:// замість HTTP-сервера — браузери відмовляються завантажувати .wasm через fetch з локального файлу через політику CORS; потрібен хоча б python3 -m http.server.
• Панічна поведінка Rust у WASM без обробника — паніка може мовчки «повісити» модуль без діагностики; крейт console_error_panic_hook, підключений на старті, перенаправляє паніку в console.error браузера.
• Недетермінована збірка через непінований інструментарій — оновлення wasm-pack чи rustc «в фоні» на CI-машині рано чи пізно дасть інший бінарник з того самого коду.

Тестування WASM-модуля

Компільований у WASM код не звільняє від дисципліни тестування — навпаки, помилка маршалінгу чи невірний тип на межі виявляється лише під час фактичного виклику з JS, а не на етапі cargo check. wasm-bindgen постачає крейт wasm-bindgen-test, що дозволяє писати тести, які реально виконуються в середовищі WASM (headless-браузер або Node.js), а не лише в нативному cargo test:

use wasm_bindgen_test::*;

#[wasm_bindgen_test]
fn greet_contains_name() {
    assert!(greet("С.І.Д.").contains("С.І.Д."));
}

wasm-pack test --headless --chrome

Це важливо саме тому, що cargo test за замовчуванням компілює й запускає тести під нативну ціль (x86-64), а не під wasm32-unknown-unknown — легко написати код, що коректно проходить нативні тести, але падає лише при фактичному виконанні в браузерному WASM-рушії через розбіжності в поведінці (наприклад, недоступність частини std під wasm32-unknown-unknown, зокрема мереж і файлової системи).

Розмір бінарника: wasm-opt і wee_alloc

Розмір .wasm-файлу напряму впливає на час першого завантаження сторінки, тому для продакшн-збірки типова практика — прогнати бінарник через wasm-opt (частина binaryen), який виконує додаткові оптимізації розміру й швидкості поза тим, що вже зробив LLVM у rustc:

wasm-opt -Oz -o pkg/sid_core_bg.wasm pkg/sid_core_bg.wasm

Прапорець -Oz пріоритизує розмір над швидкістю — доречний вибір для коду, що завантажується по мережі й виконується нечасто. Додатково стандартний алокатор Rust у wasm32-unknown-unknown можна замінити на компактніший (наприклад, wee_alloc чи, у сучасних збірках, вбудований dlmalloc з тюнінгом) — компроміс між швидкістю алокацій і розміром згенерованого коду, який варто вимірювати, а не вгадувати.

Підсумок

Rust компілюється в WASM тим самим rustc, який ми використовували для нативного коду, — просто з іншою ціллю компіляції та без операційної системи під капотом. wasm-bindgen бере на себе найважчу частину — маршалінг типів через межу, від тривіальних чисел до рядків, що фізично живуть у лінійній пам'яті модуля; wasm-pack пакує весь конвеєр (компіляція + генерація обгортки + метадані) в один виклик. Відтворювані збірки в контейнері перетворюють Rust→WASM з «якось працює в мене» на властивість, яку можна довести криптографічно. А сама тема курсу — три межі, три різні техніки ізоляції й перевірки — тут замикається: від процесу в контейнері, через пам'ять під контролем компілятора, до набору інструкцій, що виконується безпечно в чужому середовищі.