Skip to content

WebAssembly Шпаргалка

Бинарный формат инструкций для быстрого выполнения в вебе.

01

Начало работы

Загрузка Wasm в JS

WebAssembly (Wasm) — бинарный формат, выполняющийся в браузерах почти с нативной скоростью. instantiateStreaming загружает и компилирует .wasm-файл. Экспорты — функции, вызываемые из JavaScript.

webassembly
// Load and instantiate a .wasm module
WebAssembly.instantiateStreaming(fetch('module.wasm'))
  .then(result => {
    const { instance } = result;
    // call exported functions
    console.log(instance.exports.add(2, 3)); // 5
  });

// Alternative: from ArrayBuffer
const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
WebAssembly.instantiate(bytes).then(result => {
  console.log(result.instance.exports);
});

Модули и экземпляры WebAssembly

WebAssembly.Module — скомпилированное представление без состояния, безопасное для переиспользования в нескольких экземплярах. WebAssembly.Instance хранит состояние выполнения (память, глобальные переменные). Скомпилировать один раз и создать много экземпляров эффективно для параллельных воркеров.

webassembly
// Two-step: compile then instantiate
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module, importObject);
console.log(instance.exports.add(1, 2));

// Module is stateless & shareable across instances
const instance2 = await WebAssembly.instantiate(module, importObject);
// Each instance has its own memory and globals

Поддержка браузеров и определение возможностей

WebAssembly 1.0 поддерживается во всех современных браузерах. Новые предложения (SIMD, исключения, потоки, GC) требуют определения возможностей. WebAssembly.validate проверяет, что байты образуют валидный модуль, без компиляции.

webassembly
// Check basic WebAssembly support
if (typeof WebAssembly !== 'undefined') {
  console.log('WebAssembly is supported');
}

// Verify the engine can actually compile
WebAssembly.validate(new Uint8Array([
  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00
])); // true if valid module

// Feature-detect newer proposals
const hasSIMD = typeof WebAssembly.Module !== 'undefined';
const hasExceptions = 'exceptions' in WebAssembly;

Потоковая и обычная загрузка

instantiateStreaming компилирует модуль по мере передачи по сети — быстрее старт. Сервер ОБЯЗАН отдавать 'Content-Type: application/wasm'. Если CDN или статический хостинг не даёт этот заголовок, используйте путь через ArrayBuffer.

webassembly
// Streaming (preferred): compiles while downloading
WebAssembly.instantiateStreaming(fetch('m.wasm'), imports);

// Non-streaming: must download fully first
const res = await fetch('m.wasm');
const buf = await res.arrayBuffer();
WebAssembly.instantiate(buf, imports);

// Streaming requires correct MIME type:
//   Content-Type: application/wasm

Магическое число и заголовок Wasm

Магическое число бинарника Wasm — ASCII-строка '\0asm', за которой идёт 4-байтовая версия в little-endian. Этот заголовок позволяет проверить, что файл является Wasm, до компиляции. Формат организован в секции (Type, Import, Function, Memory и т. д.).

webassembly
// Every .wasm file starts with this 8-byte header:
//   0x00 0x61 0x73 0x6d  -> "\0asm"
//   0x01 0x00 0x00 0x00  -> version 1
const magic = [0x00, 0x61, 0x73, 0x6d];
const version = [0x01, 0x00, 0x00, 0x00];

// Quick validity check
function isWasm(bytes) {
  return bytes[0] === 0x00 && bytes[1] === 0x61
      && bytes[2] === 0x73 && bytes[3] === 0x6d;
}

Hello Wasm (минимальный пример)

Минимальное приложение Wasm: модуль импортирует функцию 'log' из JS и экспортирует 'greet', которая её вызывает. Формат WAT (WebAssembly Text) — читаемое человеком представление, компилируемое в бинарник через wat2wasm. Браузеры выполняют только бинарную форму.

webassembly
<!-- index.html -->
<script>
  WebAssembly.instantiateStreaming(fetch('hello.wasm'))
    .then(({ instance }) => {
      instance.exports.greet(); // logs "Hello, Wasm!"
    });
</script>

;; hello.wat (compiled to hello.wasm via wat2wasm)
(module
  (import "console" "log" (func $log (param i32)))
  (func (export "greet")
    i32.const 72   ;; 'H'
    call $log
  )
)
02

Текстовый формат WAT

Модуль и S-выражения

WAT (WebAssembly Text format) — текстовое представление Wasm. Всё обёрнуто в s-выражение (module ...). Инструкции пишутся в стековом порядке: сначала операнды, затем операция их потребляет.

webassembly
;; WAT uses s-expressions: (keyword args...)
(module
  ;; function definitions, exports, etc. go here
)

;; Nested expressions form the instruction sequence
(module
  (func $add (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add
  )
  (export "add" (func $add))
)

Комментарии в WAT

WAT поддерживает два стиля комментариев: ';;' для однострочных и '(; ... ;)' для блочных. Блочные комментарии могут вкладываться и занимать несколько строк — удобно, чтобы отключать куски кода при разработке.

webassembly
;; Single-line comment (starts with ;;)
(func (export "f")
  i32.const 1  ;; push 1
  drop         ;; discard
)

(; Block comment
   can span
   multiple lines ;)
(func (export "g")
  nop
)

Синтаксис определения функций

Функции объявляются через (func ...). Параметры задаются (param $name type), результаты — (result type). '$name' необязателен: без него функции и локальные переменные ссылаются по числовому индексу. Возврат нескольких значений требует предложения multi-value (широко поддерживается).

webassembly
;; Named function with params and result
(func $name (param $p1 i32) (param $p2 f64) (result i32)
  ;; body
)

;; Anonymous function (referenced by index)
(func (param i32) (result i32)
  local.get 0
)

;; Multiple results (multi-value proposal)
(func $swap (param i32 i32) (result i32 i32)
  local.get 1
  local.get 0
)

Inline export и import

WAT поддерживает inline-аннотации (export "name") и (import "module" "field") на функциях, памяти, таблицах и глобальных переменных — сокращение для полных форм (export ...) и (import ...). Оба варианта компилируются в идентичный бинарник.

webassembly
;; Inline export on a function
(func (export "add") (param i32 i32) (result i32)
  local.get 0
  local.get 1
  i32.add
)

;; Inline import
(func $log (import "env" "log") (param i32))

;; Inline export on memory
(memory (export "mem") 1)

;; Expanded form (equivalent)
(func $add (param i32 i32) (result i32) ...)
(export "add" (func $add))

Сегменты данных

Сегменты данных инициализируют линейную память при инстанцировании (активные) или лениво через memory.init (пассивные). Строки включают escape-последовательности вроде \00 для нулевого терминатора и \n для перевода строки. data.drop освобождает хранилище сегмента после копирования.

webassembly
;; Initialize memory with bytes at offset 0
(memory 1)
(data (i32.const 0) "Hello, Wasm!\00")

;; Named data segment (active)
(data $msg (i32.const 0) "Hello\00")

;; Passive data segment (used with memory.init)
(data $passive "lazy-loaded bytes")

;; Drop a data segment to free its memory
(data.drop $msg)

Конвертация wat2wasm и wasm2wat

WABT (WebAssembly Binary Toolkit) предоставляет wat2wasm (текст в бинарник), wasm2wat (бинарник в текст), wasm-validate и wasm-objdump. Они необходимы для инспекции, отладки и ручного написания модулей Wasm. Форма .wat — для людей; .wasm — то, что выполняют браузеры.

webassembly
# Install the WebAssembly Binary Toolkit (WABT)
# macOS:  brew install wabt
# Ubuntu: apt install wabt

# Convert text -> binary
wat2wasm hello.wat -o hello.wasm

# Convert binary -> text (disassemble)
wasm2wat hello.wasm -o hello.wat

# Validate a .wasm file
wasm-validate hello.wasm

# Print module structure
wasm-objdump -x hello.wasm
03

Типы значений

Базовые типы (i32/i64/f32/f64)

У Wasm всего четыре базовых типа значений: i32, i64, f32, f64. Знаковость целых определяется операцией (например, i32.div_s против i32.div_u), а не типом. Это держит систему типов минимальной и предсказуемой.

webassembly
;; Wasm has exactly four basic value types:
;;   i32  - 32-bit integer
;;   i64  - 64-bit integer
;;   f32  - 32-bit float
;;   f64  - 64-bit float

(func (param i32) (param i64) (param f32) (param f64)
  (result f64)
  local.get 2   ;; f32
  f64.promote_f32
)

;; Integers are signed or unsigned PER OPERATION,
;; not per type. Use i32.add_s / i32.div_u etc.

Числовые литералы в WAT

Числовые литералы в WAT поддерживают десятичную, шестнадцатеричную (0x) и двоичную (0b) формы. Float поддерживают научную запись, бесконечность (inf) и NaN. Литералы WAT по умолчанию беззнаковые: отрицательные целые кодируются с ведущим '-'.

webassembly
;; Integer literals
i32.const 42
i32.const -7
i32.const 0xff       ;; hex
i32.const 0b1010     ;; binary

;; Float literals
f64.const 3.14
f64.const 1e10
f64.const -0.0
f64.const inf
f64.const nan

;; 64-bit
i64.const 9007199254740992  ;; 2^53

Преобразования типов

Преобразования следуют единой схеме имён: extend (меньше в больше), wrap (больше в меньше), convert (int в float и обратно), reinterpret (побитовое приведение), demote/promote (точность float). Знаковые варианты используют _s, беззнаковые — _u.

webassembly
;; Extend i32 to i64
i64.extend_i32_s      ;; sign-extend
i64.extend_i32_u      ;; zero-extend

;; Wrap i64 to i32
i32.wrap_i64

;; Integer <-> Float
f32.convert_i32_s
f64.convert_i64_u
i32.trunc_f32_s       ;; truncate (toward zero)
i32.reinterpret_f32   ;; bit-level reinterpret

;; Demote / promote floats
f32.demote_f64
f64.promote_f32

Тип v128 SIMD

Тип v128 упаковывает 16 байт в один SIMD-регистр. Дорожки адресуются как i32x4 (4×int32), f32x4 (4×float32), i16x8, i8x16, f64x2. SIMD ускоряет обработку изображений, аудио и криптографию, выполняя несколько значений за инструкцию.

webassembly
;; SIMD: 128-bit vector type (fixed-width SIMD proposal)
(module
  (func (param v128) (result v128)
    local.get 0
    v128.not            ;; bitwise NOT
  )
  (func (result v128)
    v128.const i32x4 1 2 3 4
  )
)

;; Vector operations: i32x4, i16x8, i8x16, f32x4, f64x2
v128.const f32x4 1.0 2.0 3.0 4.0
i32x4.add

Ссылочные типы (funcref/externref)

Предложение reference types добавляет funcref (указатель на функцию) и externref (непрозрачная ссылка хоста). externref мощен: он позволяет Wasm держать объекты JS без копирования и сериализации. В сочетании с таблицами это включает гибкие паттерны колбэков.

webassembly
;; Reference types proposal adds:
;;   funcref   - reference to a function (in a table)
;;   externref - opaque reference to a host (JS) object

(module
  (table 1 funcref)
  (func (param externref) (result externref)
    local.get 0    ;; pass through a JS object
  )
)

;; In JS, externref lets you pass arbitrary objects
;; through Wasm without serialization:
instance.exports.store({ hello: 'world' });
04

Функции

Определение и вызов функций

Функции — фундаментальная единица кода. call вызывает функцию по имени или индексу. Аргументы кладутся на стек до вызова; результаты остаются на стеке при возврате. Стек должен соответствовать объявлению (result ...).

webassembly
(module
  (func $add (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add
  )
  (func $double (param $x i32) (result i32)
    local.get $x
    local.get $x
    i32.add      ;; or: i32.const 2  i32.mul
  )
  (func (export "use")
    i32.const 5
    i32.const 7
    call $add     ;; -> 12 on stack
    drop
  )
)

Параметры и локальные переменные

Параметры — неизменяемые локальные переменные с индексами от 0. Объявленные локальные (local $name type) инициализируются нулём и изменяемы. Используйте local.get, local.set и local.tee (set и оставить на стеке). Локальные — единственное изменяемое хранилище Wasm вне памяти и глобальных переменных.

webassembly
(func $f (param $a i32) (param $b i32) (result i32)
  (local $sum i32)         ;; mutable local
  (local $i i32)
  local.get $a
  local.get $b
  i32.add
  local.set $sum           ;; store into local
  i32.const 0
  local.set $i
  local.get $sum
)

;; tee: set and keep on stack
local.tee $sum             ;; $sum = top; stays on stack

Несколько возвращаемых значений

Предложение multi-value позволяет функциям возвращать несколько значений (и не принимать ни одного). Все крупные движки поддерживают его с 2020 года. Это убирает необходимость в out-параметрах через память и делает естественными идиомы вроде swap/minmax.

webassembly
;; Multi-value: return two i32 values
(func $minmax (param $a i32) (param $b i32) (result i32 i32)
  local.get $a
  local.get $b
  i32.lt_s
  if (result i32 i32)
    local.get $a
    local.get $b
  else
    local.get $b
    local.get $a
  end
)

;; Caller receives both on the stack
(func (export "use")
  i32.const 3
  i32.const 8
  call $minmax
  ;; stack: [min=3, max=8]
  drop drop
)

Рекурсия

Wasm поддерживает прямую рекурсию: функция может вызывать себя. В MVP Wasm нет оптимизации хвостовых вызовов (предложение tail-call добавляет return_call). Глубокая рекурсия рискует переполнить стек, поэтому в продакшене предпочитайте итеративные циклы.

webassembly
(module
  (func $fact (param $n i32) (result i32)
    local.get $n
    i32.const 1
    i32.le_s
    if (result i32)
      i32.const 1
    else
      local.get $n
      local.get $n
      i32.const 1
      i32.sub
      call $fact     ;; recursive call
      i32.mul
    end
  )
  (export "factorial" (func $fact))
)

Inline export и вызовы по имени

Inline (export "name") в определении функции — сокращение для отдельного объявления (export ...). call_ref (предложение reference types) вызывает функцию напрямую через funcref, позволяя значения-функции первого класса без поиска в таблице.

webassembly
(module
  ;; Inline export on definition
  (func $add (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )

  ;; call_ref: call via funcref (reference types)
  (func $caller (param $f funcref) (param i32) (result i32)
    local.get 1
    local.get 0
    call_ref (param i32) (result i32)
  )
)

Start-функция

Модуль может объявить одну функцию (start $func), которая выполняется автоматически при инстанцировании, — полезно для инициализации. Она не принимает аргументов и ничего не возвращает. На модуль разрешена только одна start-функция.

webassembly
(module
  (func $init
    ;; runs once at instantiation
    i32.const 0
    i32.const 42
    i32.store
  )
  (start $init)        ;; declare as start function
  (memory (export "mem") 1)
)

;; The start function runs automatically after
;; instantiation, before instantiate() resolves.
;; It takes no params and returns nothing.
05

Память

Объявление линейной памяти

Линейная память — непрерывная область вроде ArrayBuffer, растущая страницами по 64 КиБ. (memory 1 10) объявляет initial=1, max=10. Память — единственный способ передавать массовые данные (строки, массивы) между Wasm и JS. Экспортируйте её для доступа из JS.

webassembly
(module
  ;; 1 page = 64KiB. Declare 1 page, max 10.
  (memory $mem 1 10)
  (export "memory" (memory $mem))

  ;; JS-side: read/write the exported memory
  ;; const buf = new Uint8Array(instance.exports.memory.buffer);
)

Рост памяти

memory.grow добавляет страницы и возвращает предыдущий размер (в страницах) или -1 при ошибке. Важно: рост отсоединяет нижележащий ArrayBuffer — все существующие представления TypedArray становятся непригодными. Всегда пересоздавайте представления после любого вызова grow.

webassembly
(func $grow (result i32)
  i32.const 1            ;; request 1 more page
  memory.grow            ;; returns previous size (or -1)
)

;; In JS, growing detaches the old buffer!
const prev = instance.exports.grow();
const buf = new Uint8Array(instance.exports.memory.buffer);
// OLD buf references are now detached — re-create views!

Операции load и store

Загрузки и записи имеют варианты по размеру (8/16/32/64 бита) и расширению знака (_s/_u). offset=N добавляет константу к адресу-операнду; align= — подсказка (должна быть не больше размера). Все адреса — байтовые смещения в линейной памяти.

webassembly
;; Load: read from memory at address (top of stack)
i32.load  offset=0 align=2     ;; 4-byte aligned load
i32.load8_u                    ;; 1 byte, zero-extended
i32.load16_s                   ;; 2 bytes, sign-extended
f64.load                       ;; 8-byte float load

;; Store: write value at address
i32.const 100        ;; address
i32.const 42         ;; value
i32.store            ;; mem[100] = 42

i32.const 100
i32.const 0xFF
i32.store8           ;; write 1 byte

Размеры памяти и выравнивание

Выравнивание в Wasm — подсказка производительности, а не требование корректности: невыровненный доступ всегда работает. Значение 'align' не должно превышать естественный размер операции. memory.size возвращает текущее число страниц (по 64 КиБ).

webassembly
;; Each load/store has a natural alignment:
;;   i32.load   -> 4 bytes
;;   i64.load   -> 8 bytes
;;   f32.load   -> 4 bytes
;;   i32.load8  -> 1 byte

;; Explicit alignment hint (does not affect correctness)
i32.load align=2    ;; may be slower but still works

;; memory.size returns current pages
(func $pages (result i32)
  memory.size
)

Разделяемая память и атомики

Разделяемая память (предложение threads) позволяет нескольким экземплярам Wasm и воркерам делить одну память для параллелизма. Атомарные операции (i32.atomic.load/store/rmw.add/cmpxchg) дают синхронизацию. В браузерах требует cross-origin isolation (заголовки COOP/COEP).

webassembly
(module
  ;; Shared memory (threads proposal)
  (memory 1 1 shared)
  (export "memory" (memory 0))

  ;; Atomic operations
  (func (param i32 i32)
    local.get 0       ;; address
    local.get 1       ;; value
    i32.atomic.store
  )
  (func (param i32) (result i32)
    local.get 0
    i32.atomic.load
  )
  (func (param i32) (result i32)
    local.get 0
    i32.const 1
    i32.atomic.rmw.add   ;; atomic read-modify-write
  )
)

Чтение строк из памяти

У Wasm нет нативного строкового типа: строки — последовательности байтов в линейной памяти, обычно передаваемые парами (указатель, длина). TextEncoder/TextDecoder выполняют преобразование UTF-8. Всегда проверяйте, что область памяти достаточно велика, перед записью.

webassembly
// Wasm has no string type — strings live in linear memory.
// Decode UTF-8 from a (ptr, len) pair returned by Wasm:

function readString(memory, ptr, len) {
  const bytes = new Uint8Array(memory.buffer, ptr, len);
  return new TextDecoder('utf-8').decode(bytes);
}

// Writing a string into Wasm memory:
function writeString(memory, str, ptr) {
  const bytes = new TextEncoder().encode(str);
  const view = new Uint8Array(memory.buffer, ptr, bytes.length);
  view.set(bytes);
  return bytes.length; // return length
}
06

Таблицы

Объявление таблиц

Таблицы — массивы ссылок (обычно funcref) для косвенных вызовов и динамической диспетчеризации. В отличие от памяти (которая хранит байты), таблицы хранят непрозрачные ссылки, которые Wasm не может подделать. Сегменты (elem ...) инициализируют слоты таблицы при инстанцировании.

webassembly
(module
  ;; A table of function references, initial size 1
  (table 1 funcref)
  (export "table" (table 0))

  ;; With max size
  (table $t 4 16 funcref)

  ;; elem segment: initialize table slots
  (elem (i32.const 0) $fn1 $fn2 $fn3)
  (func $fn1)
  (func $fn2)
  (func $fn3)
)

Таблицы funcref и call_indirect

call_indirect диспетчеризует вызов через запись таблицы по индексу. Объявление (type ...) обязательно: Wasm в рантайме проверяет соответствие сигнатуры функции (несовпадение — ловушка). Это основа vtables и ООП-диспетчеризации в Wasm.

webassembly
(module
  (type $bin (func (param i32 i32) (result i32)))
  (table 3 funcref)

  (func $add (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (func $sub (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.sub)
  (func $mul (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.mul)

  (elem (i32.const 0) $add $sub $mul)

  (func (export "dispatch") (param i32 i32 i32) (result i32)
    local.get 0      ;; arg a
    local.get 1      ;; arg b
    local.get 2      ;; table index
    call_indirect (type $bin)
  )
)

table.grow, get и set

table.grow добавляет слоты и возвращает предыдущий размер (или -1). table.get/table.set читают и пишут записи по индексу. Рост таблицы позволяет регистрировать колбэки в рантайме. Начальный размер и max ограничивают рост, предотвращая бесконтрольное выделение.

webassembly
(func $addSlot (param funcref) (result i32)
  local.get 0
  i32.const 1            ;; grow by 1
  table.grow             ;; returns old size, or -1
)

(func $read (param i32) (result funcref)
  local.get 0
  table.get
)

(func $write (param i32 funcref)
  local.get 0     ;; index
  local.get 1     ;; funcref
  table.set
)

Таблицы externref для объектов хоста

Таблицы externref хранят непрозрачные ссылки на объекты хоста (JS): Wasm может держать их и передавать, но не может инспектировать содержимое. Это идеально для регистрации колбэков, таблиц хендлов JS и моста объектно-ориентированных JS API в Wasm.

webassembly
(module
  ;; Table holding opaque JS objects
  (table 8 externref)
  (export "table" (table 0))

  (func $store (param i32 externref)
    local.get 0
    local.get 1
    table.set
  )
  (func $load (param i32) (result externref)
    local.get 0
    table.get
  )
)

// JS: pass arbitrary objects
instance.exports.store(2, { callback: () => 42 });

Паттерн динамической диспетчеризации

Паттерн динамической диспетчеризации: храните операции в таблице, затем вызывайте call_indirect по индексу. В сочетании с обязательной проверкой типа это даёт безопасный полиморфизм в стиле vtable. Так реализуют диспетчеризацию перечисления Rust, виртуальные функции C++ и интерпретаторы.

webassembly
(module
  (type $op (func (param i32 i32) (result i32)))
  (table 4 funcref)
  (elem (i32.const 0) $add $sub $mul $div)

  (func $add (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (func $sub (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.sub)
  (func $mul (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.mul)
  (func $div (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.div_s)

  (func (export "apply") (param $op i32) (param $a i32) (param $b i32)
    (result i32)
    local.get $a
    local.get $b
    local.get $op
    call_indirect (type $op)
  )
)
07

Глобальные переменные

Объявление глобальных переменных

Глобальные — одиночные значения уровня модуля, неизменяемые (по умолчанию) или изменяемые (mut). Они живут между вызовами функций и полезны для счётчиков, флагов конфигурации и констант. Изменяемые глобальные — единственное общее изменяемое состояние вне памяти и таблиц.

webassembly
(module
  ;; Immutable global (const)
  (global $counter (mut i32) (i32.const 0))

  ;; Read-only global
  (global $pi f64 (f64.const 3.14159265))

  (func $increment
    global.get $counter
    i32.const 1
    i32.add
    global.set $counter
  )
)

Изменяемые и неизменяемые глобальные

Без 'mut' глобальная неизменяема, и global.set — ошибка компиляции. Инициализатор должен быть константным выражением (например, i32.const, ref.null, global.get импортированной неизменяемой глобальной). По умолчанию выбирайте неизменяемые ради безопасности.

webassembly
(module
  ;; (global $name type init)        -> immutable
  ;; (global $name (mut type) init)  -> mutable

  (global $version i32 (i32.const 3))
  ;; global.set $version  ;; ERROR: immutable

  (global $state (mut i32) (i32.const 0))
  (func (export "toggle")
    global.get $state
    i32.eqz
    if
      i32.const 1  global.set $state
    else
      i32.const 0  global.set $state
    end
  )
)

Импорт глобальных

Импортированные глобальные позволяют хосту внедрять значения конфигурации (или объекты WebAssembly.Global) в модуль при инстанцировании. Неизменяемые импортированные глобальные могут инициализировать другие глобальные. WebAssembly.Global — видимая в JS обёртка для изменяемых общих глобальных.

webassembly
(module
  ;; Import a global from JS
  (global $env (import "env" "version") i32)

  ;; Mutable imported global
  (global $flag (import "env" "flag") (mut i32))

  (func (export "ver") (result i32)
    global.get $env
  )
)

// JS side
const imports = {
  env: {
    version: 3,
    flag: new WebAssembly.Global({ value: 'i32', mutable: true }, 0)
  }
};

Экспорт и совместное использование

Экспортированные глобальные доступны из JS как объекты WebAssembly.Global со свойством .value (читаемым и, если изменяемое, записываемым). Совместное использование объекта Global несколькими экземплярами модуля — чистый способ координировать состояние, не трогая память.

webassembly
(module
  (global $g (export "counter") (mut i32) (i32.const 0))
  (func (export "inc")
    global.get $g
    i32.const 1
    i32.add
    global.set $g
  )
)

// JS reads/writes the global directly
const g = instance.exports.counter;
g.value;        // 0
instance.exports.inc();
g.value;        // 1
g.value = 100;  // write directly

Сценарии использования глобальных

Глобальные подходят для трёх паттернов: (1) импортированные константы конфигурации, (2) постоянные счётчики и состояние, общие для экземпляров, (3) кэшированные результаты вычислений. Для одиночных значений они проще памяти и видны нескольким экземплярам, если переданы через JS.

webassembly
(module
  ;; Configuration constants
  (global $maxSize (import "config" "maxSize") i32)
  (global $debug   (import "config" "debug")   i32)

  ;; Persistent counters
  (global $calls (mut i32) (i32.const 0))

  (func (export "handle") (result i32)
    global.get $calls
    i32.const 1
    i32.add
    global.set $calls
    global.get $calls
  )
)
08

Импорты и экспорты

Импорт функций

Импорты позволяют Wasm вызывать функции хоста (JS). Каждый импорт идентифицируется двухуровневым именем (module, field). Объект импорта, переданный в instantiate, должен совпадать с этими именами. Импорты — способ Wasm выйти во внешний мир: I/O, логирование, планирование.

webassembly
(module
  ;; Import a function under module.field naming
  (func $log (import "console" "log") (param i32))
  (func $now (import "env" "now") (result f64))

  (func (export "run")
    i32.const 42
    call $log        ;; -> console.log(42)
    call $now
    drop
  )
)

// JS
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
  console: { log: x => console.log('wasm:', x) },
  env:     { now: () => performance.now() }
});

Импорт памяти

Импорт памяти позволяет нескольким модулям Wasm (и JS) делить одну область памяти — основа Wasm-«библиотек». Один модуль выделяет и пишет, другой читает. Это компонует модули без копирования данных и предшественник component model.

webassembly
(module
  (memory (import "env" "memory") 1)
  (func (export "writeHi")
    i32.const 0
    i32.const 72     ;; 'H'
    i32.store8
  )
)

// Shared memory across multiple modules:
const memory = new WebAssembly.Memory({ initial: 1 });
WebAssembly.instantiateStreaming(fetch('a.wasm'), { env: { memory } });
WebAssembly.instantiateStreaming(fetch('b.wasm'), { env: { memory } });
// Both modules read/write the SAME memory

Импорт глобальных и таблиц

Глобальные и таблицы тоже можно импортировать, обеспечивая общее состояние и таблицы указателей на функции между модулями. WebAssembly.Table — конструктор в JS. Импортированные изменяемые глобальные позволяют хосту динамически влиять на поведение Wasm без пересборки модуля.

webassembly
(module
  (global $seed (import "env" "seed") i32)
  (table (import "env" "table") 4 funcref)

  (func (export "rand") (result i32)
    global.get $seed
    i32.const 1103515245
    i32.mul
    i32.const 12345
    i32.add
    ;; (truncated LCG step)
  )
)

// JS provides the imports
const imports = {
  env: {
    seed: 42,
    table: new WebAssembly.Table({
      element: 'funcref', initial: 4, maximum: 16
    })
  }
};

Экспорт функций, памяти и таблиц

Экспортировать можно всё, что объявлено в модуле: функции, память, таблицы, глобальные. Экспорты становятся свойствами instance.exports. Экспорт памяти даёт JS представление о линейной куче; экспорт глобальных отдаёт объекты WebAssembly.Global; экспорт таблиц — ссылки на функции.

webassembly
(module
  (memory 1)
  (table 2 funcref)
  (global $c (mut i32) (i32.const 0))

  (func (export "add") (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (export "memory" (memory 0))
  (export "table"  (table 0))
  (export "counter" (global $c))
)

// JS usage
const { add, memory, table, counter } = instance.exports;
add(2, 3);                              // 5
new Uint8Array(memory.buffer);          // raw bytes
table.get(0);                           // funcref
counter.value;                          // 0

Inline import и export

Inline-аннотации (import "m" "f") и (export "name") — синтаксический сахар: они компилируются в тот же бинарник, что и отдельные формы (import ...)/(export ...). У одного определения может быть inline export, но импорты и экспорты для импортируемых элементов объявляются отдельно.

webassembly
(module
  ;; Inline import (compact form)
  (func $log (import "env" "log") (param i32))

  ;; Inline export on function
  (func (export "add") (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add
  )

  ;; Inline export on memory
  (memory (export "mem") 1)

  ;; Inline import + export combined is NOT allowed;
  ;; a definition imports OR exports, not both.
)

Лучшие практики объекта импорта

Структурируйте объект импорта под имена (module, field) модуля. Проверяйте обязательные импорты до инстанцирования, чтобы давать понятные ошибки. Оборачивайте функции хоста в try/catch где уместно: неперехваченное исключение внутри импорта превращается в ловушку для вызывающего Wasm.

webassembly
// Build a typed import object
const imports = {
  env: {
    log:       (i) => console.log('[wasm]', i),
    now:       () => performance.now(),
    abort:     () => { throw new Error('wasm abort'); },
    memory:    new WebAssembly.Memory({ initial: 1 }),
    seed:      42,
  }
};

// Validate imports before instantiation:
function checkImports(imports, required) {
  for (const [mod, fields] of Object.entries(required)) {
    for (const f of fields) {
      if (!imports[mod]?.[f] === undefined) {
        throw new Error(`Missing import: ${mod}.${f}`);
      }
    }
  }
}
09

Control flow

block

block создаёт помеченную область, выход из которой делают ветвления (через br). Ветвления в Wasm структурированные: они могут прыгать только к концу охватывающего block/loop/if. Блок с (result ...) оставляет своё значение на стеке при переходе или обычном завершении.

webassembly
;; block: a labeled group with a single exit
(block $b
  i32.const 1
  i32.const 2
  i32.add
  ;; br $b exits the block (with optional value)
  br $b
  ;; unreachable code
)
;; stack now has the result of the block

;; Blocks can produce a value (multi-value):
(block $b (result i32)
  i32.const 42
  br $b
)

loop

loop похож на block, но br $loop прыгает к НАЧАЛУ цикла (продолжая итерацию), а не к концу. Это противоположно block. В Wasm нет ключевых слов for/while: итерация строится из loop и условного br_if.

webassembly
;; loop: a block whose br jumps back to the TOP
(func $count (param $n i32) (result i32)
  (local $i i32) (local $sum i32)
  i32.const 0  local.set $i
  i32.const 0  local.set $sum
  (loop $loop
    local.get $i
    local.get $n
    i32.lt_s
    if
      local.get $sum
      local.get $i
      i32.add
      local.set $sum
      local.get $i
      i32.const 1
      i32.add
      local.set $i
      br $loop        ;; jump back to loop start
    end
  )
  local.get $sum
)

if / else

if потребляет i32 со стека (не ноль = true). Клауза (result ...) заставляет if выдавать значение, когда обе ветви согласны по типу. if без else допустим; ветвь может быть пустой. if — сахар для block + br_if.

webassembly
;; if consumes a condition from the stack
(func $abs (param $x i32) (result i32)
  local.get $x
  if (result i32)
    local.get $x
  else
    i32.const 0
    local.get $x
    i32.sub       ;; negate
  end
)

;; if without else (no result)
(func (param i32)
  local.get 0
  if
    ;; do something only if non-zero
  end
)

br и br_if

br $label прыгает к КОНЦУ названного block/if (или к НАЧАЛУ loop). br_if делает то же условно. Метки могут быть и числовыми (br 0 = самая внутренняя). Ветвление со значением оставляет его на стеке — идиоматичный для Wasm способ раннего возврата.

webassembly
;; br: unconditional branch to a label
(block $outer
  (block $inner
    br $inner       ;; exits inner
    br $outer       ;; exits outer (unreachable here)
  )
)

;; br_if: branch only if top of stack is non-zero
(func $clamp (param $x i32) (result i32)
  (block $done (result i32)
    local.get $x
    i32.const 100
    i32.gt_s
    br_if $done          ;; if x > 100, branch with...
    i32.const 100        ;; ...100 on the stack
    local.get $x
    i32.const 0
    i32.lt_s
    br_if $done          ;; if x < 0, branch with...
    i32.const 0          ;; ...0
    local.get $x         ;; else x
  )
)

br_table (switch)

br_table реализует switch: потребляет индекс i32 и прыгает к одной из перечисленных меток или к последней (по умолчанию), если индекс вне диапазона. Вкладывайте блоки от внешнего к внутреннему, чтобы каждый случай мог вернуть своё значение. Это самый эффективный способ диспетчеризации по тегу.

webassembly
;; br_table: jump table (like a C switch)
(func $dayName (param $d i32) (result i32)
  (block $default
    (block $sat
      (block $sun
        local.get $d
        br_table $sun $sat $default
      )
      i32.const 0  ;; Sunday
      return
    )
    i32.const 6   ;; Saturday
    return
  )
  i32.const -1    ;; default
)

;; br_table $l0 $l1 $l2 ... $default
;; index 0 -> $l0, 1 -> $l1, ... out-of-range -> $default

return и unreachable

return немедленно выходит из функции со значением на стеке. unreachable всегда вызывает ловушку (бросает исключение выполнения) — используется для пометки путей, которые никогда не должны выполняться, как assert(false). Оба — выходы за пределами структурной модели блоков.

webassembly
(func $find (param $arr i32) (param $len i32) (param $key i32)
  (result i32)
  (local $i i32)
  i32.const 0  local.set $i
  (block $notFound
    (loop $loop
      local.get $i
      local.get $len
      i32.ge_s
      br_if $notFound
      ;; load arr[i] and compare...
      local.get $i
      i32.const 1
      i32.add
      local.set $i
      br $loop
    )
  )
  unreachable        ;; traps if reached
)

;; return: early exit from the function
;; unreachable: always traps (used to mark bugs)
10

Взаимодействие с JS

Передача чисел

i32/f32/f64 отображаются напрямую в числа JS. i64 отображается в BigInt (большие целые выходят за безопасный диапазон Number). Всегда используйте BigInt для параметров и возвратов i64. Преобразование на границе zero-copy, но частое пересечение имеет накладные расходы — батчируйте операции в Wasm.

webassembly
// Numbers pass directly across the Wasm/JS boundary.
const exports = instance.exports;

exports.add(2, 3);          // 5  (i32 -> JS number)
exports.square(4);          // 16
exports.compute(1.5, 2.5);  // f64 -> JS number

// i64 caveat: before BigInt integration, i64 returns
// caused problems. Now Wasm i64 maps to JS BigInt:
const big = exports.bigResult();  // 9007199254740993n

// Passing a BigInt to an i64 param:
exports.takeBigInt(123n);

Передача строк

Строки пересекают границу как последовательности байтов UTF-8: JS кодирует их в память Wasm, затем передаёт (указатель, длина). Часто Wasm экспортирует помощники alloc/free, либо вы упаковываете оба значения в один i64 (младшие 32 = ptr, старшие 32 = len). Всегда освобождайте или переиспользуйте буфер, чтобы избежать утечек.

webassembly
// Wasm has no string type. Encode UTF-8 into memory,
// pass (ptr, len) to Wasm:

function passString(memory, str) {
  const bytes = new TextEncoder().encode(str);
  const ptr = instance.exports.alloc(bytes.length);
  new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);
  instance.exports.processString(ptr, bytes.length);
  instance.exports.dealloc(ptr, bytes.length);
}

// Receiving a string back:
function recvString(memory, ptrLen) {
  const ptr = ptrLen >>> 0;
  const len = ptrLen >>> 32;
  const bytes = new Uint8Array(memory.buffer, ptr, len);
  return new TextDecoder().decode(bytes);
}

Передача массивов и массовых данных

Для массовых числовых данных смотрите на память Wasm как на TypedArray нужного типа (Float32Array, Int32Array и т. д.) и копируйте через .set(). Это самый быстрый путь, подобный memcpy. Помните о выравнивании указателей (4 байта для i32/f32, 8 байт для i64/f64) и всегда освобождайте память.

webassembly
// Write a JS array into Wasm memory:
function passArray(memory, arr) {
  const view = new Float32Array(memory.buffer);
  const ptr = instance.exports.alloc(arr.length * 4);
  const offset = ptr / 4;
  for (let i = 0; i < arr.length; i++) view[offset + i] = arr[i];
  return ptr;
}

// Faster: use TypedArray.set with a subarray
function passArrayFast(memory, arr) {
  const ptr = instance.exports.alloc(arr.length * 4);
  new Float32Array(memory.buffer, ptr, arr.length).set(arr);
  return ptr;
}

Управление памятью через границу

Память Wasm управляется вручную — сборщика мусора нет. Если Wasm экспортирует alloc/free (или вы используете помощник в стиле malloc), оборачивайте доступ из JS в try/finally, чтобы гарантировать освобождение. Следите, что memory.grow отсоединяет представления ArrayBuffer, — пересоздавайте их после роста.

webassembly
// Wasm has no GC — JS must manage allocations.
// Pattern: Wasm exports alloc/free, JS uses them:

const { memory, alloc, free, process } = instance.exports;

function withBuffer(size, fn) {
  const ptr = alloc(size);
  try {
    return fn(new Uint8Array(memory.buffer, ptr, size));
  } finally {
    free(ptr, size);
  }
}

// CAUTION: TypedArray views become detached after
// memory.grow — re-create them after any grow call.

WebAssembly.Global

WebAssembly.Global — JS-обёртка вокруг глобального значения Wasm. Создание одного и передача нескольким экземплярам модуля чисто разделяет изменяемое состояние, не трогая память. Свойство .value читает и пишет нижележащий i32/i64/f32/f64 (или v128/externref).

webassembly
// Create a global on the JS side
const counter = new WebAssembly.Global(
  { value: 'i32', mutable: true },
  0
);

// Pass to Wasm at instantiation
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
  env: { counter }
});

// Read/write from JS
counter.value;        // 0
counter.value = 10;   // set
counter.value++;      // 11

// Share across multiple instances
WebAssembly.instantiateStreaming(fetch('m2.wasm'), {
  env: { counter }    // same Global object
});

WebAssembly.Table и ошибки

WebAssembly.Table хранит ссылки на функции, доступные и из JS, и из Wasm, — полезно для реестров колбэков и таблиц диспетчеризации. Ловушки Wasm (деление на ноль, выход за границы памяти, переполнение стека) проявляются в JS как WebAssembly.RuntimeError — оборачивайте рискованные вызовы в try/catch.

webassembly
// Table of function references, callable from JS indirectly
const table = new WebAssembly.Table({
  element: 'funcref',
  initial: 4,
  maximum: 16
});

// Set a slot to a Wasm-exported function
table.set(0, instance.exports.add);
table.get(0)(2, 3);  // 5

// Errors propagate as 'RuntimeError' across the boundary:
try {
  instance.exports.divide(1, 0);
} catch (e) {
  // e instanceof WebAssembly.RuntimeError
  console.error('Wasm trapped:', e.message);
}
11

Компиляция C/C++ в Wasm

Настройка Emscripten

Emscripten — канонический тулкит для компиляции C/C++ (и языков LLVM) в Wasm. Он включает Clang, Binaryen и libc/libstdc++, портированные в браузер. Активируйте окружение в каждой сессии shell через emsdk_env. Обновления частые — периодически переустанавливайте.

webassembly
# Install the Emscripten SDK
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh   # Linux/macOS
# Windows: emsdk_env.bat

# Verify
emcc --version
# emcc (Emscripten gcc/clang-like replacement)

Hello World на C

Стандартный C работает как есть: printf пишет в виртуальный терминал, который предоставляет Emscripten. main() вызывается автоматически при загрузке модуля. Функции, вызываемые из JS, нужно экспортировать через EMSCRIPTEN_KEEPALIVE или флаг -s EXPORTED_FUNCTIONS.

webassembly
// hello.c
#include <stdio.h>

int add(int a, int b) {
    return a + b;
}

int main() {
    printf("Hello from C!\n");
    printf("2 + 3 = %d\n", add(2, 3));
    return 0;
}

Компиляция через emcc

emcc управляет компиляцией. -O3 включает агрессивные оптимизации (инлайнинг, удаление мёртвого кода). EXPORTED_FUNCTIONS перечисляет C-символы (с ведущим _) для экспорта. MODULARIZE оборачивает загрузчик в фабрику для бандлеров. Форматы вывода: только .wasm, .js-клей и .wasm или .html-демо.

webassembly
# Standalone .wasm (no main, exported functions only)
emcc add.c -O3 -o add.wasm \
  -s EXPORTED_FUNCTIONS='["_add"]' \
  -s ALLOW_MEMORY_GROWTH=1

# HTML + JS + Wasm bundle (auto-runs main)
emcc hello.c -o hello.html

# With optimizations and a specific output
emcc hello.c -O3 -s WASM=1 -o hello.js

# Common flags:
#   -O0/-O1/-O2/-O3/-Os   optimization level
#   -s MODULARIZE=1       export as JS module
#   -s EXPORT_ES6=1       ES module output
#   -s ENVIRONMENT=web    target only the web

HTML-вывод и объект Module

Объект 'Module' Emscripten — JS-рантайм: он раскрывает C-функции с префиксом _, управляет памятью (_malloc/_free) и даёт хуки (print, onRuntimeInitialized). MODULARIZE превращает его в фабрику, возвращающую Promise, что подходит для бандлеров и асинхронной загрузки.

webassembly
// Generate a runnable HTML demo
//   emcc hello.c -o hello.html
// Then open hello.html in a browser.

// Modularized loader (use from JS):
//   emcc hello.c -o hello.js -s MODULARIZE=1 -s EXPORT_NAME='createModule'

import createModule from './hello.js';

const Module = await createModule({
  print: (text) => console.log('C said:', text),
  onRuntimeInitialized: () => {
    Module._main();          // call main
    const sum = Module._add(2, 3);
    console.log('sum:', sum);  // 5
  }
});

Вызов JS из C (EM_JS / EM_ASM)

EM_JS определяет JS-функцию inline, которую C может вызывать напрямую, — эффективно и синхронно. EM_ASM встраивает inline-фрагмент JS. Используйте $0, $1, ... для аргументов. Эти макросы связывают C с API браузера (DOM, fetch, Web Audio), не требуя отдельных JS-биндингов.

webassembly
#include <emscripten.h>

// EM_JS: define a JS function callable from C
EM_JS(void, callAlert, (int x), {
  alert("Value from C: " + x);
});

// EM_ASM: inline JS (use $n for arguments)
void logValue(int n) {
  EM_ASM({
    console.log("C passed:", $0);
  }, n);
}

int main() {
  callAlert(42);
  logValue(99);
  return 0;
}

Поддержка файловой системы (MEMFS)

Emscripten предоставляет MEMFS — виртуальную файловую систему в памяти. fopen/fread/fwrite работают как в C. Используйте --preload-file, чтобы встроить ресурсы в sidecar .data при компиляции. Для персистентного хранилища IDBFS синхронизируется с IndexedDB; NODERAWFS открывает реальную ФС в Node.

webassembly
#include <stdio.h>
#include <emscripten.h>

int main() {
    // MEMFS: a virtual in-memory filesystem
    FILE *f = fopen("/tmp/data.txt", "w");
    fprintf(f, "Hello, MEMFS!\n");
    fclose(f);

    f = fopen("/tmp/data.txt", "r");
    char buf[64];
    fgets(buf, sizeof(buf), f);
    fclose(f);
    printf("%s", buf);
    return 0;
}

// Preload files at compile time:
//   emcc app.c -o app.html \
//     --preload-file assets/data.txt
12

Компиляция Rust в Wasm

Настройка wasm-pack

Rust компилируется в Wasm через цель wasm32-unknown-unknown. wasm-pack — рекомендуемый инструмент: он оборачивает cargo, запускает wasm-bindgen и создаёт пакет, готовый для npm. Для целей WASI используйте wasm32-wasi.

webassembly
# Install Rust (rustup)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add the wasm32 target
rustup target add wasm32-unknown-unknown

# Install wasm-pack (the canonical Wasm tool for Rust)
cargo install wasm-pack
# or: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Verify
wasm-pack --version

Структура библиотеки Rust

wasm-bindgen — мост между Rust и JS. #[wasm_bindgen] помечает элементы для экспорта. Строки, Vec<u8> и объекты JS преобразуются автоматически. Атрибут constructor раскрывает new() как JS-конструктор. Это генерирует JS-клей, благодаря которому Rust ощущается нативным.

webassembly
// src/lib.rs
use wasm_bindgen::prelude::*;

// Export a function callable from JS
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

// Export a struct with methods
#[wasm_bindgen]
pub struct Counter {
    count: i32,
}

#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter {
        Counter { count: 0 }
    }
    pub fn increment(&mut self) -> i32 {
        self.count += 1;
        self.count
    }
}

Сборка через wasm-pack

wasm-pack build создаёт публикуемый npm-пакет: бинарник .wasm, JS-клей и файлы TypeScript .d.ts. --target web даёт самодостаточный ES-модуль для прямого использования в браузере; --target bundler интегрируется с webpack/vite. Сгенерированные типы дают полное автодополнение TS.

webassembly
# Build for the browser (npm package output)
wasm-pack build --target web

# Targets:
#   --target web       ES module, modern browsers
#   --target bundler   for webpack/rollup/vite
#   --target nodejs    CommonJS for Node.js
#   --target no-modules  global-based

# Output goes to ./pkg/
#   my_crate.js       JS glue
#   my_crate_bg.wasm  the binary
#   my_crate.d.ts     TypeScript types

# Use in JS:
import init, { add } from './pkg/my_crate.js';
await init();           // load the .wasm
console.log(add(2, 3)); // 5

wasm-bindgen: взаимодействие с JS

Блоки extern импортируют функции и классы JS в Rust. js_namespace = console вызывает console.log. method раскрывает JS-методы на импортированных типах. wasm-bindgen обрабатывает преобразования строк (Rust &str в JS string и обратно) и владение — без ручного управления памятью.

webassembly
use wasm_bindgen::prelude::*;

// Call a JS function from Rust
#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str);
}

#[wasm_bindgen]
pub fn run() {
    log("Hello from Rust!");
}

// Import a JS class
#[wasm_bindgen(module = "/js/util.js")]
extern "C" {
    pub type JsCounter;
    #[wasm_bindgen(constructor)]
    pub fn new() -> JsCounter;
    #[wasm_bindgen(method)]
    pub fn tick(this: &JsCounter) -> i32;
}

Вызов JS из Rust и паники

Импортированные JS-функции выглядят как обычные функции Rust. Используйте console_error_panic_hook, чтобы получать читаемые трассировки паник Rust в консоли браузера (по умолчанию паники вызывают ловушку без сообщения). Атрибут #[wasm_bindgen(start)] запускает main() при инстанцировании — как main в C.

webassembly
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(&format!("Hello, {}!", name));
}

// Install a panic hook for readable errors:
#[wasm_bindgen(start)]
pub fn main() {
    console_error_panic_hook::set_once();
}
13

AssemblyScript

Настройка и Hello World

AssemblyScript — язык в стиле TypeScript, компилируемый в Wasm. Он нацелен на разработчиков, которые хотят производительность Wasm, не изучая C/Rust. Синтаксис повторяет TS, но со строгими типами (i32 вместо number). Используйте загрузчик или импортируйте .wasm напрямую.

webassembly
# Install AssemblyScript compiler
npm install -g assemblyscript
# or use the boilerplate:
npm init assemblyscript my-app
cd my-app
npm install
npm run asbuild

// assembly/index.ts
export function add(a: i32, b: i32): i32 {
  return a + b;
}

// Load from JS:
import { instantiate } from "@assemblyscript/loader";
const module = await instantiate(fetch("build/release.wasm"));
console.log(module.exports.add(2, 3)); // 5

Типы в AssemblyScript

В отличие от TypeScript, AssemblyScript требует конкретные числовые типы: i32, i64, f32, f64, u8, u16, u32 и т. д. 'number' отвергается при компиляции. StaticArray избегает GC; ArrayBuffer/TypedArray повторяют JS API. Именно строгая типизация позволяет компилировать в эффективный Wasm.

webassembly
// Distinct numeric types (NOT just 'number')
let a: i32 = 42;
let b: i64 = 9007199254740993n;
let f: f64 = 3.14;
let u: u32 = 100;

// Bool, string, arrays
let flag: bool = true;
let s: string = "hi";
let arr: i32[] = [1, 2, 3];

// Static arrays (no GC overhead)
let sa: StaticArray<i32> = [1, 2, 3];

// TypedArray-like
let buf: ArrayBuffer = new ArrayBuffer(8);

Память и строки

В AssemblyScript есть небольшой GC для управляемых объектов (Array, Map, String). Используйте __retain/__release для контроля времени жизни при переходе в JS. @assemblyscript/loader предоставляет __getString, __newString, __getArray и т. д. для моста через границу.

webassembly
// Strings are UTF-16 in AssemblyScript memory
export function greet(name: string): string {
  return "Hello, " + name + "!";
}

// Manual memory management for buffers
export function process(len: i32): i32 {
  let buf = new ArrayBuffer(len);
  // ...fill buf...
  let result = __retain(buf);  // prevent GC
  return result;
}

// In JS, use the loader's __getString/__newString:
const ptr = module.exports.greet("World");
console.log(module.exports.__getString(ptr));

Экспорты и точки входа

Функции и классы, помеченные export, становятся экспортами Wasm. Классы отображаются в JS-совместимые объекты через загрузчик. _start — согласованная точка входа (как main в C). Стандартная библиотека AssemblyScript повторяет JS Math, Array, Map, что делает переход мягким.

webassembly
// assembly/index.ts
export function fib(n: i32): i32 {
  if (n < 2) return n;
  return fib(n - 1) + fib(n - 2);
}

export class Vector {
  constructor(public x: f32, public y: f32) {}
  magnitude(): f32 {
    return Math.sqrt(this.x * this.x + this.y * this.y);
  }
}

// Module start function (runs at instantiation)
export function _start(): void {
  // initialization code
}

Компиляция и оптимизации

asc — компилятор AssemblyScript. --optimize (-O) запускает wasm-opt из Binaryen. --runtime управляет GC: 'full' (по умолчанию), 'half' (меньше), 'none' (вручную). --importMemory позволяет делить память между модулями. Source maps позволяют отлаживать в исходном .ts.

webassembly
# Build debug vs release
npm run asbuild           # both debug and release
# or:
asc assembly/index.ts --outFile release.wasm --optimize

# Common flags
asc index.ts -o release.wasm \
  --optimize \
  --noAssert \
  --runtime half          # smaller GC runtime
  --importMemory          # use imported memory
  --sourceMap             # emit source map

# Optimize for size:
asc index.ts -o tiny.wasm --optimize --runtime none \
  --conformance --noDebug
14

WASI (WebAssembly System Interface)

Что такое WASI

WASI — переносимый системный интерфейс на основе возможностей для Wasm вне браузера. В отличие от веба, где Wasm вызывает JS, WASI даёт Wasm прямой (песочный) доступ к файлам, сети и окружению. Безопасность на основе возможностей означает, что программа может трогать только ресурсы, явно для неё открытые.

webassembly
// WASI = WebAssembly System Interface
// A standardized API for Wasm to access OS capabilities:
//   - filesystem (files, directories)
//   - network sockets (preview2)
//   - environment variables, args
//   - clocks, random numbers
//   - process exit

// Capability-based security: a Wasm program can
// ONLY access resources it was explicitly granted.

// Targets:
//   wasm32-wasi           (preview1)
//   wasm32-wasip1         (preview1, new name)
//   wasm32-wasip2         (preview2, component model)

// Runtimes: wasmtime, wasmer, WasmEdge, browser_wasi_shim

Runtime wasmtime

wasmtime — эталонный WASI-рантайм от Bytecode Alliance. --dir предоткрывает каталог хоста (давая доступ к файлам). --env передаёт переменные окружения. --net включает сеть в preview2. Без явных разрешений программа Wasm ничего не видит — так работает безопасность на возможностях.

webassembly
# Install wasmtime (the reference WASI runtime)
# macOS:  brew install wasmtime
# Linux:  curl https://wasmtime.dev/install.sh -sSf | bash
# Windows: scoop install wasmtime

# Run a WASI module
wasmtime hello.wasm

# Pass arguments
wasmtime hello.wasm arg1 arg2

# Preopen a directory (grant filesystem access)
wasmtime --dir=. app.wasm

# Set environment variables
wasmtime --env FOO=bar app.wasm

# Allow network (preview2)
wasmtime --net allow app.wasm

Запуск Wasm с WASI (пример на C)

Программы для WASI выглядят как обычные C-программы на libc. Компилируйте через clang --target=wasm32-wasi с sysroot WASI (скачайте релиз wasi-sdk). Один и тот же .wasm работает на wasmtime, wasmer, WasmEdge и других WASI-хостах без перекомпиляции — настоящая переносимость.

webassembly
// wasi_hello.c
#include <stdio.h>
#include <unistd.h>

int main(int argc, char *argv[]) {
    printf("Hello from WASI!\n");
    printf("argc = %d\n", argc);
    for (int i = 0; i < argc; i++) printf("  argv[%d] = %s\n", i, argv[i]);
    return 0;
}

# Compile with the WASI SDK
clang --target=wasm32-wasi \
  --sysroot=/path/to/wasi-sysroot \
  -o hello.wasm wasi_hello.c

# Run
wasmtime hello.wasm foo bar
# Hello from WASI!
# argc = 3
#   argv[0] = hello.wasm
#   argv[1] = foo
#   argv[2] = bar

Доступ к файловой системе WASI

WASI раскрывает файловый API в стиле POSIX (open, read, write, close). Файлы вне предоткрытых каталогов невидимы. Используйте --dir=path:alias, чтобы дать доступ и переименовать. WASI preview2 вводит интерфейсы component model (wasi filesystem, wasi sockets) для более богатых API.

webassembly
// wasi_fs.c — read a file passed via --dir
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>

int main() {
    int fd = open("input.txt", O_RDONLY);
    if (fd < 0) { perror("open"); return 1; }
    char buf[256];
    ssize_t n = read(fd, buf, sizeof(buf) - 1);
    if (n > 0) { buf[n] = '\0'; printf("%s", buf); }
    close(fd);
    return 0;
}

# Grant access, then run:
#   wasmtime --dir=. wasi_fs.wasm

Окружение и аргументы WASI

WASI предоставляет аргументы и переменные окружения через стандартные C-интерфейсы (argv, environ, getenv). Хост контролирует, что видно: --env даёт конкретные переменные. Это делает программы Wasm настраиваемыми без изменений кода и ограничивает утечку секретов хоста.

webassembly
// wasi_env.c
#include <stdio.h>
#include <stdlib.h>

extern char **environ;

int main(int argc, char *argv[]) {
    printf("Args:\n");
    for (int i = 0; i < argc; i++) printf("  %s\n", argv[i]);

    printf("Env:\n");
    for (char **e = environ; *e; e++) printf("  %s\n", *e);

    const char *home = getenv("HOME");
    printf("HOME=%s\n", home ? home : "(unset)");
    return 0;
}

# Run with env vars:
#   wasmtime --env HOME=/tmp --env FOO=bar wasi_env.wasm a b c

WASI sockets (preview)

WASI sockets — часть preview2 (component model). wasi:sockets/tcp и wasi:sockets/udp дают сеть; wasi:http предлагает HTTP-клиент более высокого уровня. API стабилизируются, поэтому сегодня для переносимости предпочитайте wasi:http. Рантаймы вроде wasmtime и WasmEdge реализуют их.

webassembly
// WASI preview2 adds TCP/UDP sockets.
// In Rust (using wasi crate):
use wasi::sockets::network::{IpAddress, IpSocketAddress};

// Component-model based sockets:
//   - wasi:sockets/tcp
//   - wasi:sockets/udp
//   - wasi:sockets/ip-name-lookup

# Compile a Rust program for preview2:
cargo build --target wasm32-wasip2 --release

# Run with network access:
wasmtime --net allow target/wasm32-wasip2/release/myapp.wasm

// Note: socket APIs are still stabilizing.
// Use HTTP via wasi:http/types for stability.
15

Отладка

wasm-objdump

wasm-objdump (из WABT) печатает структуру модуля: типы, импорты, экспорты, сигнатуры функций, дизассемблер кода и размеры секций. -x даёт сводку высокого уровня; -d дизассемблирует тела функций в инструкции в стиле WAT. Необходим, чтобы понять, что модуль реально содержит.

webassembly
# Inspect a .wasm file's structure
wasm-objdump -x module.wasm       # everything
wasm-objdump -d module.wasm       # disassemble functions
wasm-objdump -s module.wasm       # raw section contents
wasm-objdump -j Import -x m.wasm  # only the Import section

# Sample -x output:
# Section Type (1) at 0x0008:
#   type[0] (i32, i32) -> i32
# Section Function (3) at 0x0015:
#   func[0] type=0

wasm2wat для инспекции

wasm2wat превращает бинарник .wasm обратно в читаемый WAT. Это бесценно для понимания сторонних модулей, отладки неожиданного поведения и реверс-инжиниринга. Круговой цикл (wasm2wat, правка, wat2wasm) сохраняет поведение, делая WAT полноценным исходным форматом.

webassembly
# Disassemble binary to readable text
wasm2wat module.wasm -o module.wat

# View in your editor
cat module.wat

# Round-trip: edit .wat, recompile
wat2wasm module.wat -o module.wasm

# Common inspection: find exports
grep "(export" module.wat

# Find imports
grep "(import" module.wat

DevTools браузера

Все крупные браузеры умеют отлаживать Wasm в DevTools: смотреть дизассемблированный WAT, ставить точки останова, инспектировать локальные и стек вызовов. С source maps (Rust, AssemblyScript, Emscripten -g) DevTools отображает обратно на исходный код. Отладочная информация DWARF даёт более богатую отладку C/C++/Rust.

webassembly
// Chrome/Edge/Firefox DevTools support Wasm debugging:
//   1. Sources tab -> file tree shows .wasm entries
//   2. Click a .wasm to view disassembled WAT
//   3. Set breakpoints on function entries
//   4. Inspect the call stack and locals

// With source maps (Rust/AS), DevTools shows the
// ORIGINAL source (.rs / .ts) instead of WAT.

// Enable in chrome://flags:
//   "WebAssembly debugging: Support DWARF"

// Console logging from Wasm:
//   Import a JS log function and call it from WAT.
//   Rust: wasm_logger / console_log crate.
//   AS:   console.log via env import.

Source maps

Source maps связывают инструкции Wasm с исходным языком. Rust генерирует их через wasm-pack; AssemblyScript через --sourceMap; Emscripten через -g4. Комментарий sourceMappingURL в .wasm (кастомная секция) указывает DevTools, где искать .map. Без него вы отлаживаете сырой WAT.

webassembly
# Rust: source maps come automatically with wasm-pack
wasm-pack build --target web --dev

# AssemblyScript: emit source maps
asc index.ts -o release.wasm --sourceMap \
  --sourceMap include 'src/**/*.ts'

# Emscripten: include debug info and source map
emcc app.c -g4 -O0 -o app.js \
  --source-map-base http://localhost:8000/

# The .map file points DevTools back to the
# original .rs / .ts / .c source files.

# Validate a source map exists:
wasm-objdump -x app.wasm | grep sourceMappingURL

Частые ошибки и ловушки

Повторяющиеся ошибки Wasm: отсутствующие импорты (несовпадение имён и типов), ловушки (unreachable, выход за границы памяти, переполнение при делении на ноль), отсоединённые ArrayBuffer (после grow) и проблемы на границе i64. Оборачивайте рискованные вызовы в try/catch и проверяйте импорты и указатели заранее, чтобы выявлять проблемы рано.

webassembly
// 1. LinkError: "import not found"
//    Cause: import object missing a name.
const imports = { env: { log: console.log } };
// Must match (import "env" "log" ...) exactly.

// 2. RuntimeError: "unreachable"
//    Cause: Wasm executed unreachable / panic / assert.

// 3. RuntimeError: "out of bounds memory access"
//    Cause: load/store at an invalid address.
//    Fix: check ptr/len before access; grow memory.

// 4. CompileError: "section size mismatch"
//    Cause: corrupted or truncated .wasm file.

// 5. TypeError: "i64 not supported"
//    Cause: i64 returns without BigInt integration.
//    Fix: use BigInt, or return two i32 values.

// 6. "detached ArrayBuffer"
//    Cause: used a TypedArray view after memory.grow.
//    Fix: re-create views after grow.
16

Оптимизация производительности

Инлайнинг и флаги -O

-O3 включает агрессивный инлайнинг и оптимизации циклов. wasm-opt (Binaryen) запускает дополнительные проходы на уровне Wasm (инлайнинг, мёртвый код, свёртка констант) — всегда запускайте его для продакшена. -Os/-Oz меняют часть скорости на меньший размер загрузки. -flto включает оптимизацию всей программы.

webassembly
# Compilation optimization levels
emcc app.c -O0 -o app.wasm   # no optimization (debug)
emcc app.c -O1 -o app.wasm   # basic
emcc app.c -O2 -o app.wasm   # standard
emcc app.c -O3 -o app.wasm   # aggressive (inlining)
emcc app.c -Os -o app.wasm   # optimize for size
emcc app.c -Oz -o app.wasm   # max size reduction

# Post-optimize with Binaryen
wasm-opt -O3 app.wasm -o app.opt.wasm
wasm-opt -Os app.wasm -o app.small.wasm

# LTO across translation units (C/C++)
emcc app.c -flto -O3 -o app.wasm

Раскладка памяти и паттерны доступа

Линейная память Wasm — просто ArrayBuffer, поведение кэша CPU применимо. Непрерывные паттерны доступа (row-major для row-major данных) кардинально быстрее страйд-доступа. Поддерживайте естественное выравнивание (4 байта для i32), чтобы load/store попадали в одиночные инструкции.

webassembly
// Cache-friendly access: linear, contiguous iteration
// GOOD: row-major traversal of a 2D array
for (i32 row = 0; row < rows; row++) {
  for (i32 col = 0; col < cols; col++) {
    sum += data[row * cols + col];
  }
}

// BAD: column-major traversal (cache misses)
for (i32 col = 0; col < cols; col++) {
  for (i32 row = 0; row < rows; row++) {
    sum += data[row * cols + col];
  }
}

// Prefer aligned access (4-byte for i32, 8 for i64).
// Allocators should respect natural alignment.

Минимизация пересечений границы JS

Каждый вызов JS в Wasm имеет накладные расходы (маршалинг аргументов, подготовка стека). Для плотных циклов переносите цикл ВНУТРЬ Wasm и вызывайте один раз с буфером. Это главный совет по производительности Wasm: массовые операции превосходят поэлементные вызовы на порядки.

webassembly
// BAD: call Wasm per element (boundary overhead)
for (let i = 0; i < arr.length; i++) {
  result[i] = exports.process(arr[i]);
}

// GOOD: batch — one call for the whole array
const ptr = exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
exports.processBatch(ptr, arr.length);   // single call
const out = Array.from(new Float32Array(memory.buffer, ptr, arr.length));
exports.free(ptr, arr.length * 4);

// Each crossing costs ~tens of nanoseconds.
// Batch loops to amortize the overhead.

SIMD (одна инструкция, много данных)

SIMD (v128) обрабатывает 4 float или 4 int32 за инструкцию — ускорение до 4x для изображений, аудио и матричной математики. Emscripten включает его через -msimd128; Rust использует интринсики std::arch::wasm32. Автовекторизация может помочь, но явные интринсики дают предсказуемый выигрыш. Широко поддерживается в браузерах.

webassembly
// C/C++ with Emscripten auto-vectorization
#include <emscripten/simd.h>
void addArrays(float *a, float *b, float *out, int n) {
    for (int i = 0; i < n; i += 4) {
        v128_t va = wasm_v128_load(a + i);
        v128_t vb = wasm_v128_load(b + i);
        wasm_v128_store(out + i, wasm_f32x4_add(va, vb));
    }
}

# Compile with SIMD enabled
emcc simd.c -O3 -msimd128 -o simd.wasm

// Rust: use std::arch::wasm32 intrinsics
use std::arch::wasm32::*;
unsafe { let v = f32x4_splat(1.0); }

Потоки и SharedArrayBuffer

Потоки Wasm делят Memory между Web Workers, используя атомики для синхронизации. Требуют заголовков COOP/COEP (cross-origin isolation). -pthread в Emscripten эмулирует pthreads; std::thread в Rust работает на wasm32-wasi-threads. Отлично для CPU-bound параллельной работы: обработка изображений, кодеки, инференс ML.

webassembly
// Enable threads in Emscripten
# emcc app.c -O3 -pthread -s PTHREAD_POOL_SIZE=4 -o app.js

// Browser requires cross-origin isolation:
//   /_headers (Cloudflare/Netlify)
//   Cross-Origin-Opener-Policy: same-origin
//   Cross-Origin-Embedder-Policy: require-corp

// Spawn workers sharing Wasm memory:
const memory = new WebAssembly.Memory({
  initial: 10, maximum: 100, shared: true
});
// Each Worker instantiates the module with this memory
// and uses Atomics for synchronization.

Профилирование и бенчмарки

Профилируйте через performance.now() и вкладку Performance в DevTools: Wasm появляется на flame chart как JS. Прогревайтесь перед измерением (накладные расходы компиляции одноразовые). Сравнивайте с оптимизированным JS: современный V8 быстр; Wasm выигрывает на предсказуемой производительности, числовых ядрах и больших нагрузках, а не на микрозадачах.

webassembly
// Use performance.now() for high-res timing
const t0 = performance.now();
exports.heavyWork(ptr, len);
const t1 = performance.now();
console.log(`Wasm: ${(t1 - t0).toFixed(2)}ms`);

// Compare against JS equivalent
const t2 = performance.now();
jsEquivalent(data);
console.log(`JS:   ${(performance.now() - t2).toFixed(2)}ms`);

// Chrome DevTools Performance tab: profile Wasm
// like JS — flame charts show function time.

// Avoid microbenchmarks pitfalls:
//   - warm up first (JIT compilation)
//   - run many iterations
//   - compare against OPTIMIZED JS, not naive JS
17

Wasm и JavaScript

Сравнение производительности

Wasm блистает на вычислительно тяжёлой числовой работе (обработка изображений, кодеки, криптография, ML) — обычно в 2–10 раз быстрее JS. Для DOM, JSON и работы со строками JS часто быстрее, потому что работа уже в нативном коде (JSON.parse в V8, DOM браузера). Профилируйте, чтобы решить, — никогда не предполагайте, что Wasm всегда быстрее.

webassembly
// Wasm vs JS — typical scenarios:
//
// Image processing (8MB):
//   JS:          120 ms
//   Wasm (-O3):   35 ms    ~3.4x faster
//
// SHA-256 (1MB):
//   JS:           45 ms
//   Wasm:          8 ms    ~5.6x faster
//
// DOM manipulation:
//   JS:            5 ms
//   Wasm:         20 ms    SLOWER (DOM is JS-native)
//
// JSON parse:
//   JS:            3 ms
//   Wasm:         15 ms    SLOWER (JSON.parse is C++ in V8)
//
// Rule of thumb: Wasm wins on compute-heavy numeric
// workloads; JS wins on DOM/JSON/string-heavy tasks.

Сценарии использования Wasm

Wasm особенно хорош для: портирования существующих кодовых баз C/C++/Rust (Figma, Photoshop web), вычислительных числовых ядер (изображения, ML, криптография) и песочных плагинов. Реальные успехи: Figma (рендерер), Photoshop (полный порт приложения) и Google Meet (размытие фона). Для чистых DOM-приложений JS обычно правильный выбор.

webassembly
// Strong Wasm use cases:
//   - Image/video/audio processing (FFmpeg, OpenCV)
//   - Games & 3D engines (Unity, Unreal)
//   - Cryptography (hashing, encryption, ZK proofs)
//   - Machine learning inference (ONNX, TFLite)
//   - Codecs (AV1, VP9, MP3)
//   - Emulators (DOSBox, retro consoles)
//   - Heavy math (physics simulations, linear algebra)
//   - Reusing C/C++/Rust libraries (FFI alternative)
//   - Sandboxed plugins in editors (Figma, Photoshop)

// Figma: rendering engine in Wasm
// Photoshop: web port of full desktop app
// Google Meet: video background blur

Когда использовать JS

JS остаётся правильным выбором для UI, DOM, API браузера и большей части логики веб-приложений: V8 сильно оптимизирован. Тянитесь к Wasm, когда профилирование выявило горячую точку, которую JS не может оптимизировать, или когда портируете существующую нативную кодовую базу. Гибридный подход (JS UI и горячие точки на Wasm) часто идеален.

webassembly
// JS is better when:
//   - DOM manipulation dominates
//   - Working with browser APIs (fetch, IndexedDB, WebRTC)
//   - Heavy string/JSON processing
//   - Small utilities and glue code
//   - Rapid prototyping (no compile step)
//   - Team lacks C/Rust expertise
//   - Module size matters more than runtime speed

// JS engines (V8, SpiderMonkey, JSC) are highly
// optimized. For most web apps, JS is fast enough
// AND simpler to ship and maintain.

// Hybrid: keep UI in JS, offload hotspots to Wasm.

Загрузка и стоимость старта

У Wasm фиксированная стоимость старта (загрузка, компиляция, инстанцирование), которой JS избегает. Смягчайте потоковой компиляцией, кэшированием скомпилированных модулей через Cache API и ленивой загрузкой некритичного Wasm. После прогрева вызовы функций Wasm так же быстры, как JS: стоимость впереди, но окупается более быстрым выполнением.

webassembly
// Wasm has upfront costs JS doesn't:
//   1. Download the .wasm binary
//   2. Compile to machine code (~10-50 ms for small modules)
//   3. Instantiate (initialize memory, run start function)

// Mitigations:
//   - Cache compiled modules (WebAssembly.compileStreaming + Cache API)
//   - Stream compilation (instantiateStreaming)
//   - Lazy-load non-critical Wasm on demand
//   - Use Web Workers to compile off the main thread

// Streaming compile of a 1MB module:
//   ~30 ms download + ~10 ms compile (parallel)
// Cached: ~5 ms (re-instantiate from cached module)

Стоимость взаимодействия и границы

Вызовы JS и Wasm дешевы, но не бесплатны (~10–100 нс каждый, больше для строк). Для высокочастотных событий батчируйте в JS и вызывайте Wasm один раз с буфером. Избегайте передачи объектов JS на каждый вызов: используйте externref или копируйте байты в память. Граница быстра для чисел и медленна для сериализованных данных.

webassembly
// Each JS<->Wasm call costs ~10-100 ns:
//   - Marshal arguments (i32/f64 fast; strings/objects slow)
//   - Stack frame setup
//   - Inlined trampoline in the engine

// Implications:
//   - Don't call Wasm 1M times for tiny work — batch!
//   - Don't pass large objects per-call — copy once, share memory
//   - For DOM events, keep handlers in JS, call Wasm with batched data

// Pseudocode: batched event handling
let pendingEvents = [];
button.addEventListener('click', e => {
  pendingEvents.push(...);
  if (pendingEvents.length >= 100) {
    exports.processBatch(ptr, pendingEvents.length);
    pendingEvents = [];
  }
});
18

Модель безопасности

Модель песочницы

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

webassembly
// Wasm executes in a sandboxed virtual machine:
//   - No direct access to host memory (only its linear memory)
//   - No syscalls (must go through imported functions)
//   - No I/O unless the host provides it
//   - Control flow is structured (no arbitrary jumps)
//   - Type-checked at compile and run time

// All host access is EXPLICIT through imports.
// A module that didn't import "fs" cannot read files.

// Code:
//   (module
//     (import "env" "log" (func (param i32)))
//     ;; the ONLY host capability this module has is log()
//   )

Same-origin policy и fetch

Wasm не выходит за модель безопасности браузера: same-origin policy и CORS применяются к загрузке .wasm как к любому ресурсу. Кросс-доменный Wasm требует корректных заголовков CORS и MIME-типа application/wasm. Wasm также не может обойти CSP, cookies или другие механизмы безопасности браузера.

webassembly
// Wasm modules obey the same-origin policy:
//   - fetch('https://other-origin/x.wasm') needs CORS headers
//   - The remote server must send:
//       Access-Control-Allow-Origin: *
//   - And the correct MIME: application/wasm

// Load cross-origin Wasm with streaming:
const { instance } = await WebAssembly.instantiateStreaming(
  fetch('https://cdn.example.com/lib.wasm', {
    mode: 'cors'
  }),
  imports
);

// Wasm cannot bypass CORS — it's subject to the
// browser's normal security model.

Изоляция памяти

Память Wasm проверяется на границы в рантайме: любое обращение вне границ сразу вызывает ловушку, а не портит память. Модули не могут читать память друг друга, кучу JS или произвольные адреса хоста. Указатели на функции (call_indirect) проверяются по типу, что предотвращает подделку цели вызова. Это устраняет целые классы уязвимостей C/C++.

webassembly
// Each Wasm instance has its OWN linear memory.
//   - Out-of-bounds access traps (RuntimeError)
//   - One module's memory cannot read another's
//   - JS writes via TypedArray views are bounds-checked

// Even shared memory (threads) requires explicit
// opt-in and is still bounded:
const mem = new WebAssembly.Memory({ initial: 1, maximum: 10 });

// Wasm code CANNOT:
//   - Read JS heap
//   - Read other instances' memory
//   - Forge function pointers (call_indirect type-checks)
//   - Read arbitrary host memory addresses

// All memory access is bounds-checked at runtime.

Безопасность на основе возможностей

Wasm следует безопасности на основе возможностей: объект импорта И ЕСТЬ возможности модуля. Аккуратно выбирая, что импортировать, вы даёте модулю минимальные привилегии. Плагин, импортирующий только log(), не может ничего другого. Это основа безопасных систем плагинов (Figma, Shopify functions и т. д.).

webassembly
// Capability security: a module can ONLY do what
// the host explicitly grants via imports.

// Strict imports = minimal privilege
const imports = {
  env: {
    log: msg => console.log('[wasm]', msg)
    // NO file IO, NO network, NO timers
  }
};
WebAssembly.instantiateStreaming(fetch('plugin.wasm'), imports);

// The plugin can ONLY call log(). It cannot:
//   - Access the DOM
//   - Make network requests
//   - Read files
//   - Spawn workers
// unless you import those capabilities.

CSP и Trusted Types

Content Security Policy относится к Wasm как к eval: по умолчанию CSP его блокирует. Добавьте 'wasm-unsafe-eval' в script-src, чтобы разрешить Wasm, оставив eval() заблокированным. Это мягче, чем unsafe-eval, и рекомендуется для продакшена. Совместимость с Trusted Types требует обернуть любой динамический JS-клей в политику.

webassembly
// Content Security Policy applies to Wasm:
//   - 'wasm-unsafe-eval' is required for instantiation
//   - Without it, CSP blocks WebAssembly.compile

// HTTP header:
//   Content-Security-Policy:
//     default-src 'self';
//     script-src 'self' 'wasm-unsafe-eval';

// Wasm output (e.g., Emscripten) often uses eval-like
// patterns for instantiation — CSP 'wasm-unsafe-eval'
// specifically allows Wasm while still blocking eval().

// Trusted Types: Wasm glue code must produce
// trusted scripts; use policy.createScript() for
// any dynamically generated JS that loads Wasm.
19

Инструменты

WABT (wat2wasm, wasm2wat)

WABT — канонический тулкит для работы с текстовым и бинарным форматами Wasm. wat2wasm/wasm2wat делают круговой цикл; wasm-objdump инспектирует структуру; wasm-interp запускает модули в эталонном интерпретаторе. wasm-decompile выдаёт читаемую форму в стиле C. Необходим для ручного написания, отладки и обучения.

webassembly
# WABT = WebAssembly Binary Toolkit
# Install:
#   macOS:  brew install wabt
#   Ubuntu: apt install wabt
#   Windows: scoop install wabt

# Tools included:
wat2wasm hello.wat -o hello.wasm       # text -> binary
wasm2wat hello.wasm -o hello.wat       # binary -> text
wasm-validate hello.wasm               # validate
wasm-objdump -x hello.wasm             # inspect structure
wasm-interp hello.wasm                 # interpret (run)
wasm-decompile hello.wasm -o hello.dly # decompile to C-like

# Online: https://webassembly.github.io/wabt/demo/

Emscripten SDK

Emscripten — самый зрелый Wasm-тулкит: компилирует C/C++, Fortran и другие языки LLVM. emcc/em++ оборачивают Clang; emcmake/emconfigure позволяют собирать существующие проекты CMake/Autotools без изменений. Он также предоставляет libc, SDL, OpenGL (через WebGL) и порты pthreads для совместимости.

webassembly
# Emscripten: compile C/C++/LLVM languages to Wasm
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest
source ./emsdk_env.sh

# Key tools:
emcc        # C/C++ compiler (gcc/clang-like)
em++        # C++ compiler
emcmake     # wrapper for cmake
emconfigure # wrapper for ./configure
emranlib    # archive tool
emar        # archiver

# Common output:
emcc app.c -O3 -o app.js   # JS glue + .wasm
emcc app.c -o app.html     # runnable HTML demo

wasm-pack (Rust)

wasm-pack — официальный инструмент сборки Rust в Wasm: собирает, запускает wasm-bindgen, генерирует типы TypeScript и упаковывает для npm. --target выбирает формат JS-модуля. wasm-pack test запускает тесты Rust в реальных браузерах через webdriver. Используйте wasm-pack-template для готового каркаса проекта.

webassembly
# wasm-pack: build, test, publish Rust Wasm packages
cargo install wasm-pack

# Build for various targets
wasm-pack build --target web       # modern browsers
wasm-pack build --target bundler   # webpack/vite
wasm-pack build --target nodejs    # Node.js

# Test in a headless browser
wasm-pack test --headless --chrome

# Publish to npm
wasm-pack publish

# Generate a template project
cargo generate --git https://github.com/rustwasm/wasm-pack-template

Binaryen (wasm-opt)

Binaryen — тулкит оптимизации, который Emscripten и wasm-pack используют внутри. wasm-opt запускает проходы на уровне Wasm (инлайнинг, удаление мёртвого кода, свёртка констант) — всегда запускайте его в продакшен-сборках. -O3 для скорости, -Oz для минимального размера. wasm-metadce удаляет неиспользуемые экспорты между модулями.

webassembly
# Binaryen: Wasm optimization toolkit
# Often installed via Emscripten or standalone:
npm install -g binaryen

# wasm-opt: optimize .wasm files
wasm-opt -O3 input.wasm -o output.wasm       # speed
wasm-opt -Os input.wasm -o output.wasm       # size
wasm-opt -Oz input.wasm -o output.wasm       # min size

# Other tools:
wasm-as input.wat -o output.wasm             # assemble
wasm-dis input.wasm -o output.wat            # disassemble
wasm-merge a.wasm b.wasm -o merged.wasm      # link
wasm-shell input.wat                         # interpreter
wasm-metadce input.wasm -o output.wasm       # aggressive dead-code

wasm-tools (Bytecode Alliance)

wasm-tools — современный тулкит на Rust от Bytecode Alliance. Он парсит, печатает и валидирует, но его главная особенность — поддержка component model (component new/embed/describe). Для многих операций он строже и быстрее WABT и рекомендуется для работы с component model.

webassembly
# wasm-tools: modern Rust-based Wasm toolkit
cargo install wasm-tools

# Subcommands:
wasm-tools parse input.wat -o output.wasm      # text -> binary
wasm-tools print input.wasm -o output.wat      # binary -> text
wasm-tools validate input.wasm                 # validate
wasm-tools component new input.wasm -o c.wasm  # wrap as component
wasm-tools strip input.wasm -o stripped.wasm   # remove debug info
wasm-tools objdump input.wasm                  # inspect
wasm-tools smith                                # generate random modules (fuzzing)

# Component model support is a key feature.
# Stronger WAT parsing than WABT in edge cases.

Рантаймы (wasmtime, wasmer, WasmEdge)

Три крупных standalone-рантайма: wasmtime (эталон Bytecode Alliance, лучшая поддержка component model), wasmer (несколько бэкендов, включая LLVM для пиковой производительности, JS-биндинги), WasmEdge (CNCF, оптимизирован для cloud-native и AI-инференса). Все реализуют WASI, поэтому один .wasm работает в них. Выбирайте по соответствию экосистеме.

webassembly
# wasmtime — Bytecode Alliance reference runtime
curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime app.wasm

# wasmer — cross-platform, multiple backends
curl https://get.wasmer.io -sSf | sh
wasmer run app.wasm

# WasmEdge — CNCF, optimized for cloud/edge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
wasmedge app.wasm

# Comparison:
#   wasmtime:  reference, WASI preview1+2, components
#   wasmer:   multiple backends (Cranelift, LLVM), JS API
#   WasmEdge:  AI/ML extensions, Kubernetes-friendly

// All three run WASI modules portably.
20

Компоненты и лучшие практики

Обзор Wasm Components

Component Model — эволюция Wasm: формат модуля, позволяющий компонентам обмениваться богатыми типами (строки, записи, списки) без ручного маршалинга через линейную память. Компоненты компонуются как библиотеки между языками (компонент Rust и компонент JS). Поддерживается wasmtime, WasmEdge и более широкой экосистемой Bytecode Alliance.

webassembly
// Component Model: a higher-level module format
// that lets Wasm modules talk to each other and hosts
// using rich types (strings, records, variants),
// not just (i32, f64).

// Core Wasm module:  exports raw functions over memory.
// Component:         wraps a core module, exposes typed
//   interfaces described in WIT (Wasm Interface Type).

// Build flow:
//   1. Write WIT interface
//   2. Generate bindings for your language (Rust, C, JS)
//   3. Implement, compile to core .wasm
//   4. Wrap into a component with wasm-tools

// Tooling:
wasm-tools component new app.wasm -o app.wasm

// Run with wasmtime:
wasmtime app.wasm  # uses component interfaces

WIT (Wasm Interface Type)

WIT (Wasm Interface Type) — IDL для компонентов: объявляйте записи, варианты, перечисления, ресурсы и функции. wit-bindgen генерирует биндинги для конкретных языков (Rust, C, JS, Python). Ключевое слово 'world' объединяет импорты и экспорты, которые компонент предоставляет и потребляет. Это основа переносимых, языконезависимых библиотек Wasm.

webassembly
// example.wit — describe a component's interface
package example:greeter;

interface api {
    // A record type
    record person {
        name: string,
        age: u32,
    }

    // A function taking/returning rich types
    greet: func(p: person) -> string;
}

world greeter-world {
    export api;
}

# Generate bindings:
#   Rust:     cargo component bindings
#   JS:       jco transpile
#   C/C++:    wit-bindgen c component.wit

# wit-bindgen is the binding generator
cargo install wit-bindgen-cli

Практика: небольшие сфокусированные модули

Предпочитайте несколько небольших сфокусированных модулей Wasm одному монолиту. Меньшие модули быстрее скачиваются, лучше кэшируются и могут загружаться лениво (аудиомодуль — только когда нужен). Делите память между модулями через импорты или используйте component model для типобезопасных вызовов между модулями. Запускайте wasm-opt -Oz на каждом.

webassembly
// GOOD: One focused .wasm per concern
//   - renderer.wasm (drawing)
//   - audio.wasm (mixing)
//   - physics.wasm (simulation)
// Loaded lazily as needed.

// BAD: One giant monolithic .wasm
//   - app.wasm (1MB+, includes everything)

// Benefits of small modules:
//   - Faster initial load (only what's needed)
//   - Better caching (changed modules re-download)
//   - Easier parallel development
//   - Smaller attack surface per module

// Use wasm-opt -Oz to minimize each module.
// Share memory across modules via imports.

Практика: обработка ошибок

Ловушки Wasm (деление на ноль, выход за границы памяти, unreachable) нельзя перехватить изнутри Wasm — они прерывают функцию. Проектируйте экспортируемые функции так, чтобы они возвращали коды ошибок или типы Result, а не вызывали ловушки. Перехватывайте WebAssembly.RuntimeError на стороне JS как последнее средство. Component model поддерживает типизированные варианты ошибок нативно.

webassembly
// Wasm traps are unrecoverable — handle errors gracefully.

// BAD: let divide crash
(func (export "div") (param i32 i32) (result i32)
  local.get 0  local.get 1  i32.div_s  ;; traps on 0
)

// GOOD: return a sentinel or error code
(func (export "div") (param i32 i32) (result i32)
  local.get 1
  i32.eqz
  if (result i32)
    i32.const -1   ;; error sentinel
  else
    local.get 0
    local.get 1
    i32.div_s
  end
)

// In Rust/AS: use Result<T, E> and export
// error variants via the component model.

Практика: управление памятью

Относитесь к памяти Wasm как к C: каждому alloc нужен парный free. Экспортируйте помощники alloc/free и оборачивайте использование буфера из JS в try/finally. Пересоздавайте представления TypedArray после любого memory.grow (ArrayBuffer отсоединяется). Документируйте владение: кто отвечает за освобождение — вызывающий или вызываемый? Утечки со временем ухудшают производительность.

webassembly
// Export alloc/free and use them consistently.
// C/C++ (Emscripten): _malloc / _free
// Rust:               wasm_bindgen's __alloc / __free
// AssemblyScript:     __new / __retain / __release

// JS wrapper for safe buffer passing:
function withBuffer(size, fn) {
  const ptr = exports.alloc(size);
  try {
    return fn(new Uint8Array(memory.buffer, ptr, size));
  } finally {
    exports.free(ptr, size);
  }
}

// NEVER leak:
//   - Re-create TypedArray views after memory.grow
//   - Free buffers passed in from JS
//   - For long-lived allocations, document ownership

Практика: тестирование и CI

Тестируйте Wasm в реальных окружениях: wasm-pack test запускает тесты Rust в headless-браузерах; у AssemblyScript и Emscripten свои раннеры. Добавьте wasm-validate и проверки размера в CI. Используйте -s ASSERTIONS=1 (Emscripten) и debug-сборки, чтобы ловить проблемы рано. Линтуйте через wat2wasm и всегда запускайте wasm-opt на релизных артефактах.

webassembly
# Test Wasm just like any other code.

# Rust: wasm-pack test runs in a real browser
wasm-pack test --headless --chrome --firefox

# AssemblyScript: use the built-in test framework
npm run test

# C/C++ (Emscripten): use emcc with -s ASSERTIONS=1
#   and write tests in C, run with node:
node tests.js

# Validate .wasm in CI:
wasm-validate module.wasm

# Check size budgets:
ls -la module.wasm  # e.g., must be < 200KB

# Lint WAT with wat2wasm (catches syntax errors)
# Run wasm-opt -O3 to ensure optimization is applied

# GitHub Actions example:
# - uses: actions-rs/toolchain@v1
# - run: cargo install wasm-pack
# - run: wasm-pack test --headless

Was this helpful?