← Cloudflare Workers / workers / languages

Rust

Cloudflare Workers поддерживает Rust благодаря workers-rs крейт ↗, который делает Runtime API и привязки к продуктам платформы для разработчиков, таким как Workers KV, R2, а также Queues, доступный напрямую из вашего кода на Rust.

Следуя этому руководству, вы научитесь создавать Worker полностью на языке программирования Rust.

Прежде чем приступить к этому руководству, убедитесь, что у вас есть:

• Последняя версия Rust ↗
• npm ↗
• Rust wasm32-unknown-unknown набор инструментов:

rustup target add wasm32-unknown-unknown

• И cargo-generate подкоманду, выполнив:

cargo install cargo-generate

Откройте окно терминала и выполните следующую команду, чтобы сгенерировать шаблон проекта Worker на Rust:

cargo generate cloudflare/workers-rs

Ваш проект будет создан в новом каталоге с указанным вами именем, в котором вы найдёте следующие файлы и папки:

• Cargo.toml - Стандартный файл конфигурации проекта для пакетного менеджера Rust Cargo ↗ менеджер пакетов. Шаблон уже содержит рекомендуемые настройки для сборки Wasm на Workers.
• wrangler.toml - Конфигурация Wrangler, предварительно заполненная пользовательской командой сборки для вызова worker-build (см. Сборка в Wrangler).
• src - Каталог исходного кода Rust, предварительно заполненный примером Worker Hello World.

После создания первого Worker выполните wrangler dev команду, чтобы запустить локальный сервер для разработки Worker. Это позволит вам тестировать Worker в процессе разработки.

npx wrangler dev

Если вы раньше не использовали Wrangler, он попытается открыть веб-браузер для входа в аккаунт Cloudflare.

Перейдите в http://localhost:8787 ↗ чтобы посмотреть, как работает ваш Worker. Любые изменения в коде запускают пересборку, а перезагрузка страницы покажет актуальный результат работы Worker.

После создания нового проекта напишите код Worker. Точку входа Worker можно найти в src/lib.rs:

use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, ctx: Context) -> Result<Response> {
    Response::ok("Hello, World!")
}

workers-rs предоставляет API среды выполнения, максимально соответствующий JavaScript API Worker, и обеспечивает интеграцию с возможностями платформы Worker. Подробную документацию по API см. в docs.rs/worker ↗.

Этот макрос позволяет определять точки входа для вашего Worker. Макрос event макрос поддерживает следующие события:

• fetch - Вызывается входящим HTTP-запросом.
• scheduled - Вызывается Cron Triggers.
• queue - Вызывается входящими пакетами сообщений из Queues (требуется queue функцию в Cargo.toml, см. workers-rs репозиторий GitHub и queues флаг функции ↗).
• start - Вызывается при первом запуске Worker (например, для установки обработчиков паники).

fetch обработчик предоставляет три аргумента, соответствующих JavaScript API:

1. Request ↗

Объект, представляющий входящий запрос. Включает методы для доступа к заголовкам, методу, пути, свойствам Cloudflare и телу запроса (с поддержкой асинхронной потоковой передачи и десериализации JSON с помощью Serde ↗).

2. Env ↗

Предоставляет доступ к Worker привязки.

• Secret ↗ - Значение секрета, настроенное в панели управления Cloudflare или с помощью wrangler secret put.
• Var ↗ - Переменная окружения, определённая в wrangler.toml.
• KvStore ↗ - Workers KV привязка пространства имён.
• ObjectNamespace ↗ - Durable Object привязку.
• Fetcher ↗ - Service binding другому Worker.
• Bucket ↗ - R2 привязка Bucket.
• D1Database ↗ - D1 привязку к базе данных.
• Queue ↗ - Queues привязку producer.
• Ai ↗ - Workers AI привязку.
• Hyperdrive ↗ - Hyperdrive привязку.
• AnalyticsEngineDataset ↗ - Analytics Engine привязку.
• DynamicDispatcher ↗ - Dynamic Dispatch привязку.
• SecretStore ↗ - Secrets Store привязку.
• RateLimiter ↗ - Rate Limiting привязку.

3. Context ↗

Предоставляет доступ к waitUntil (отложенные асинхронные задачи) и passThroughOnException функциональность (fail open).

fetch обработчик ожидает Response ↗ тип возвращаемого значения, который поддерживает асинхронную потоковую передачу ответов клиенту. Это также тип возвращаемого значения любых подзапросов, выполняемых из вашего Worker. Есть методы для доступа к коду статуса и заголовкам, а также для потоковой передачи тела ответа асинхронно или его десериализации из JSON с помощью Serde ↗.

Реализует удобные API маршрутизации ↗ чтобы обслуживать несколько путей из одного Worker. См. раздел Router пример в worker-rs репозиторий GitHub ↗.

Настроив проект, теперь можно развернуть Worker в *.workers.dev поддомен, или Custom Domain, если он у вас настроен. Если у вас не настроен ни поддомен, ни домен, Wrangler предложит настроить его в процессе развёртывания.

npx wrangler deploy

Откройте предпросмотр Worker по адресу <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

После выполнения этих шагов у вас будет развёрнут базовый Worker на основе Rust. Далее вы можете добавлять зависимости и писать код на Rust для реализации своего Worker-приложения. Если вы хотите подробнее узнать, как Workers поддерживают код на Rust, скомпилированный в Wasm, следующий раздел описывает используемые библиотеки и инструменты.

Workers на Wasm вызываются из JavaScript-скрипта точки входа, который создаётся автоматически при использовании workers-rs.

Чтобы использовать функции платформы, такие как привязки, Wasm Workers должны иметь доступ к методам JavaScript runtime API.

Эта совместимость достигается за счёт wasm-bindgen ↗, который предоставляет связующий код, необходимый для импорта runtime API в модуль Wasm и экспорта обработчиков событий из него. wasm-bindgen также предоставляет js-sys ↗, который реализует типы для взаимодействия с объектами JavaScript. На практике это деталь реализации, поскольку workers-rs: API берёт на себя преобразование в объекты JavaScript и обратно, а также взаимодействие с импортированными JavaScript API среды выполнения.

wasm-bindgen-futures ↗ (часть wasm-bindgen проект) обеспечивает совместимость между Rust Futures и JavaScript Promises. workers-rs вызывает всю функцию обработчика события с помощью spawn_local, то есть вы можете писать код на асинхронном Rust, который преобразуется в единый JavaScript Promise и выполняется в цикле событий JavaScript. Вызовы импортированных runtime API JavaScript автоматически преобразуются в Rust Futures, которые можно вызывать из асинхронных функций Rust.

Чтобы запустить полученный бинарный файл Wasm в Workers, workers-rs включает инструмент сборки под названием worker-build ↗ который:

1. Создает точку входа JavaScript, которая корректно вызывает модуль с помощью wasm-bindgen: JavaScript API.
2. Вызывает web-pack для минификации и сборки кода JavaScript.
3. Создает структуру каталогов, которую Wrangler может использовать для сборки и развертывания итогового Worker.

worker-build по умолчанию вызывается в шаблонном проекте с помощью пользовательской команды сборки, указанной в wrangler.toml файл.

Неоптимизированные бинарные файлы Rust Wasm могут быть большими, превышать лимиты размера бандла Worker или приводить к долгому запуску. В шаблонном проекте заранее настроено несколько полезных оптимизаций размера в вашем Cargo.toml файле:

[profile.release]
lto = true
strip = true
codegen-units = 1

Наконец, worker-bundle автоматически вызывает wasm-opt ↗ чтобы дополнительно уменьшить размер бинарного файла перед загрузкой.

• Rust Wasm Book ↗