Запуск компонентов WebAssembly (экспериментально)¶
tarantool-wasm - модуль
Tarantool, запускающий компоненты WebAssembly рядом с данными: код приложения
на Python, JavaScript, Go, Rust, C или C#, вызываемый из Lua через
require('wasm'). Компоненты собираются с помощью
tarawasm.
tt wasm prepare подготавливает проект для обоих инструментов, пока tt не
собирает компоненты сам, а tt wasm new добавляет компонент в пакет.
tt wasm - это модуль wasm, один из
стандартных модулей tt, который проверяет в том числе файлы .wasm пакета. Для работы требуются
Linux x86-64 или macOS arm64, Tarantool 3.6 или новее и Python 3.10 или новее
для tarawasm. Linux arm64 не поддерживается: сборки tarantool-wasm для него нет,
поэтому ни на одном rock-сервере нет rock-модуля wasm для установки на этой
платформе, если только не упаковать локальную сборку (tt wasm rock --from).
На этой странице компонент Python add(a, b) собирается в пакет myapp.
HTTP API в компоненте WebAssembly -
целое приложение: HTTP-сервер в компоненте, записывающий данные в space.
Подготовка проекта¶
В каталоге пакета, где находится app.manifest.toml:
$ tt wasm prepare --lang python
declared wasm 0.1.0 from https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/
installing tarawasm
...
checking the python toolchain
python toolchain:
python3 >=3.10.0 3.14.4 ok /usr/bin/python3
wasm-tools 1.261.0 1.261.0 ok .../.tarantool/bin/wasm-tools (installed by tt)
wkg 0.16.1 0.16.1 ok .../.tarantool/bin/wkg (installed by tt)
componentize-py 0.25.1 0.25.1 ok .../.tarantool/bin/componentize-py (installed by tt)
...
prepared for tarantool-wasm 0.1.0 (linux-x86_64)
rock: from https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/
tarawasm: .tarantool/bin/tarawasm
toolchains: python
Вывод pip и tarawasm выводится между этими строками, на месте .... Что
сделала команда:
-
объявила rock
wasm- нативный модуль релиза - в манифесте и пересчитала локфайл:[dependencies] wasm = { version = "0.1.0", registry = "https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/" }
Сервер - это rock-индекс
tarantool-contrib/rocks-repo, раздающий rock для каждой платформы с его
sha256, поэтому локфайл фиксирует их все, а следующий tt package build
устанавливает rock этой машины, проверенный по локфайлу;
- установила tarawasm в виртуальное окружение в .tarantool/versions/ и
создала ссылку .tarantool/bin/tarawasm;
- развернула набор инструментов Python, см. ниже;
- записала .env/activate.sh, добавляющий .tarantool/bin в PATH оболочки.
.tarantool относится к этой машине и не коммитится. После checkout, на другой
машине или в CI tt wasm prepare восстанавливает всё: tarawasm, набор
инструментов каждого компонента и SDK, зафиксированный каждым компонентом.
Наборы инструментов¶
tarawasm управляет компиляторами для каждого языка. Из них tt устанавливает в
проект те инструменты, которые можно целиком взять из их релизов, проверяя
каждый по известному tt sha256, в .tarantool/versions/ со ссылкой в
.tarantool/bin:
| Инструмент | Для | |
|---|---|---|
| wasm-tools 1.261.0, wkg 0.16.1 | все языки | релизы Bytecode Alliance |
| componentize-py 0.25.1 | python |
wheel, который pip устанавливает в окружение tarawasm из скачанного tt файла |
| TinyGo 0.43.0 с Binaryen 133 | go |
Binaryen ставится поверх TinyGo, которому в версии 0.43 нужен wasm-opt; на него тоже создаётся ссылка |
| wit-bindgen 0.62.0 | c |
|
| wasi-sdk 34 | c |
не добавляется в .tarantool/bin, чтобы его clang не подменял системный компилятор при каждой сборке: для каждого C-компонента tarawasm получает путь к нему из tarawasm.local.json |
Остальные инструменты устанавливаются вручную: tt проверяет их версии, сообщает, что установить, и ничего не ставит в систему.
| Язык | Устанавливаемые инструменты |
|---|---|
python |
python3 3.10 или новее |
go |
Go 1.25 - 1.27 |
rust |
rustc и cargo 1.96 или новее с target wasm32-wasip1, cargo-component 0.21.1 |
js |
Node 24 или новее, jco 1.37.0 с componentize-js 0.23.0 и preview2-shim 0.17.8 |
c |
ничего дополнительного |
csharp |
.NET SDK 10.0.402, в Linux x86-64 |
Отсутствующий инструмент или неподходящая версия останавливают команду с сообщением о том, что именно нужно установить:
$ tt wasm prepare --lang rust
...
⨯ the toolchain is not ready for rust; install, tt does not:
rustc >=1.96.0 (missing): rustup (https://rustup.rs), then rustup target add wasm32-wasip1
cargo >=1.96.0 (missing): rustup (https://rustup.rs)
cargo-component >=0.21.1 (missing): cargo install --locked cargo-component --version 0.21.1
Набор инструментов проверяется так же, как его находит сборка: сначала в
.tarantool/bin, затем в PATH. Команда tarawasm toolchain setup --install,
устанавливающая инструменты сама, запускает sudo apt-get install на Linux и
собирает wasm-tools и wkg из исходного кода; tt никогда её не запускает.
Добавление компонента¶
$ tt wasm new calc --lang python
...
added component calc in calc
tarawasm создаёт компонент в calc/ на SDK того релиза wasm, который
объявлен в пакете, а calc/.gitignore оставляет сгенерированные файлы вне git.
WIT world компонента назван по его имени; так же назван и результат сборки,
dist/calc.wasm: компоненты пакета не конфликтуют. Манифест объявляет
компонент:
# A WebAssembly component, made by tt wasm new and built by tarawasm.
[components.calc]
path = "calc"
include = ["dist/calc.wasm"]
[components.calc.build]
backend = "shell"
command = "tarawasm"
args = ["all"]
incremental = true
tarawasm all заново генерирует bindings и собирает dist/calc.wasm; сборка
находит tarawasm и компиляторы в .tarantool/bin как с .env/activate.sh, так
и без него. incremental = true пропускает сборку, пока исходный код, WIT и
локфайл SDK компонента остаются теми же, что и при прошлой сборке; после смены
компилятора tt package build --rebuild пересобирает компонент в любом случае.
См. Инкрементальные сборки.
Lua-компонент проекта с path = "." по умолчанию забирает все лежащие ниже
*.so: укажите для него exclude = ["calc/"].
SDK компонента зафиксирован в его tarawasm.tarantool.lock.json и должен
соответствовать релизу, объявленному в пакете: компонент собирается под WIT
своего SDK, а модуль отдаёт собственный WIT. tt wasm prepare отклоняет
компонент на другом SDK, а tt wasm status перечисляет такие расхождения в
списке причин, мешающих сборке проекта; tt package build ничего о них не
сообщает.
Написание компонента¶
Флаг --template создаёт компонент Python по образцу: call соответствует
примеру ниже, http - серверу из руководства
HTTP API в компоненте WebAssembly;
затем tt wasm new выводит Lua-модуль, использующий компонент.
$ tt wasm new calc --lang python --template call
Без шаблона добавьте экспорт в world в файле calc/wit/app.wit, куда его
записывает tarawasm:
package example:app@0.1.0;
world calc {
include tarantool:tarantool/guest@0.2.0;
import docs:adder/ssl-bio@0.1.3;
export add: func(a: s32, b: s32) -> s32;
}
и реализуйте его в calc/main.py ниже инициализации, созданной tarawasm:
import twr_python_sdk
twr_python_sdk.install(ports=['ssl', 'asyncio_dns'])
import wit_world
class WitWorld(wit_world.WitWorld):
def add(self, a: int, b: int) -> int:
return a + b
См. руководство по tarawasm для остальных языков и API Tarantool в компоненте.
Сборка и вызов из Lua¶
$ tt package build
$ find .rocks -name wasm.so -o -name '*.wasm'
.rocks/lib/tarantool/wasm.so
.rocks/share/tarantool/myapp/dist/calc.wasm
Файл .wasm пакета - размещаемый компонентом или записываемый его сборкой в
share/ - обязан быть бинарным файлом WebAssembly: всё остальное приводит к
ошибке сборки, а core module, который require('wasm') не загружает,
раскладывается с предупреждением.
Компонент - это файл пакета в пространстве имён пакета. Загружайте его по пути от каталога приложения (рабочего каталога экземпляров) как в проекте, так и в установленной версии:
local wasm = require('wasm')
local calc = wasm.load('.rocks/share/tarantool/myapp/dist/calc.wasm')
assert(wasm.call(calc, 'add', 20, 22) == 42)
local bound = wasm.bind(calc)
assert(bound.add(1, 2) == 3)
wasm.drop(calc)
$ tt run -e "local wasm = require('wasm') \
local calc = wasm.load('.rocks/share/tarantool/myapp/dist/calc.wasm') \
print(wasm.call(calc, 'add', 20, 22)) os.exit()"
42
os.exit() завершает выполнение: без него Tarantool продолжит читать скрипт из
стандартного ввода или откроет консоль в терминале.
Модуль держит скомпилированные компоненты в ~/.cache/wasmtime пользователя, от
имени которого запущен Tarantool, и продолжает работу без кэша, если не может
туда писать.
Проверка проекта¶
tt wasm status показывает, что подготовила команда tt wasm prepare и что
требуется для сборки, ничего не изменяя: rock wasm и его сборку для этой
машины, tarawasm, каждый компонент с зафиксированным в нём SDK и наборы
инструментов. При любых недостающих компонентах или инструментах команда
завершается с ошибкой, как при проверке в CI:
$ tt wasm status
wasm: 0.1.0 from https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/
rock: from https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/
tarawasm: .tarantool/bin/tarawasm
component: calc (python, SDK 0.1.0) in calc
python toolchain:
...
ready
Упаковка¶
Упаковка с зависимостями выполняется по умолчанию: архив содержит модуль для платформы, на которой собран пакет, и сам компонент.
$ tt package pack
.../_build/pack/myapp-1.0.0-linux-amd64.tt
$ tt package install _build/pack/myapp-1.0.0-linux-amd64.tt --scope user --yes
installed myapp 1.0.0 into user scope
Архив, упакованный с --without-deps, получает суффикс -any.tt, если у пакета
нет собственных нативных файлов: при установке он скачивает rock wasm для
машины, куда устанавливается, с rock-сервера, сверяя его по локфайлу архива.
Публикация rock¶
Rock-индекс tarantool-contrib/rocks-repo раздаёт rock для каждой платформы.
Собственный rock-сервер делает то же самое: tt wasm rock упаковывает rock
каждой сборки релиза вместе с индексом, превращающим каталог в rock-сервер:
$ tt wasm rock --out dist/rocks
.../dist/rocks/wasm-0.1.0-1.linux-x86_64.rock
.../dist/rocks/wasm-0.1.0-1.macosx-aarch64.rock
.../dist/rocks/manifest
.../dist/rocks/tt-rocks-index.json
Раздавайте этот каталог или загрузите его файлы рядом с ассетами релиза и объявите зависимость оттуда:
$ tt wasm prepare --rock-server https://github.com/tarantool/tarantool-wasm-rs/releases/download/v0.1.0/
...
rock: from https://github.com/tarantool/tarantool-wasm-rs/releases/download/v0.1.0/
Объявляется любая версия, которую раздаёт сервер, независимо от того, знает ли
tt этот релиз. Локальная сборка модуля упаковывается только для этой машины - в
.tarantool/registry, rock-сервер внутри проекта, - и объявляется оттуда:
$ tt wasm prepare --from target/release/libtarantool_wasm_rs.so
reading the build in target/release/libtarantool_wasm_rs.so
packed wasm-0.1.0-1.linux-x86_64.rock into .tarantool/registry
declared wasm 0.1.0 from .tarantool/registry
...
Этот реестр существует только на текущей машине: после checkout запустите
tt wasm prepare --from заново, а для установки на другой машине упакуйте пакет
вместе с зависимостями.
Команды и параметры¶
| Команда | |
|---|---|
tt wasm prepare |
rock wasm, tarawasm, наборы инструментов и SDK компонентов |
tt wasm new NAME --lang L |
компонент |
tt wasm status |
чего не хватает для сборки, без изменений; ошибка при отсутствии любого элемента |
tt wasm rock --out DIR |
rocks всех платформ релиза для rock-сервера |
--versionуprepareиrockвыбирает релиз tarantool-wasm: любой, раздаваемый rock-сервером, дляprepare, либо известный tt дляprepare --fromиrock; список известных выводитtt wasm prepare --help.--rock-server URLуprepareобъявляет rock с указанного rock-сервера (по умолчанию - rock-индекс tarantool-contrib/rocks-repo).--from FILEуprepareупаковывает локальную сборку модуля в.tarantool/registryи объявляет rock оттуда; уrock- упаковывает её в--outкак rock для--arch.--pythonуprepareзадаёт Python для установки tarawasm,--tarawasm- то, что pip ставит вместо зафиксированного в tt tarawasm,--no-tarawasmпропускает его установку,--reinstallпереустанавливает заново.--langуprepareпопутно разворачивает набор инструментов дляpython,go,js,rust,cилиcsharp; дляnewон обязателен.--dirуnewзадаёт каталог компонента,--world- имя его WIT world (по умолчанию совпадает с именем компонента), а--template-httpилиcallдля Python.
Загруженные файлы кэшируются в каталоге кэша пользователя, на Linux это
~/.cache/tt/wasm. TT_WASM_RELEASES задаёт JSON-файл с релизами, которые tt
использует вместо встроенных, вместе с base_url для их ассетов: это зеркало
для сетей без доступа к интернету; его формат описан в разделе
Переменные окружения.