← Cloudflare Workers / workers / languages

Rust

Cloudflare Workers podporuje Rust prostřednictvím workers-rs crate ↗, což způsobuje, že Runtime API a vazby k produktům vývojářské platformy, jako je Workers KV, R2, a Queues, dostupné přímo z vašeho kódu v Rustu.

Podle tohoto návodu se naučíte, jak vytvořit Worker zcela v programovacím jazyce Rust.

Než začnete s tímto průvodcem, ujistěte se, že máte:

• Nedávná verze Rust ↗
• npm ↗
• Rust wasm32-unknown-unknown toolchain:

rustup target add wasm32-unknown-unknown

• A cargo-generate podpříkaz spuštěním:

cargo install cargo-generate

Otevřete okno terminálu a spuštěním následujícího příkazu vygenerujte šablonu projektu Workeru v Rustu:

cargo generate cloudflare/workers-rs

Váš projekt se vytvoří v novém adresáři, který jste pojmenovali, a najdete v něm tyto soubory a složky:

• Cargo.toml - Standardní konfigurační soubor projektu pro Rustův Cargo ↗ manažer balíčků. Šablona předvyplní některá doporučená nastavení pro sestavení Wasm na Workers.
• wrangler.toml - Konfigurace Wrangler, předvyplněná vlastním build příkazem pro volání worker-build (Viz Bundling ve Wrangleru).
• src - Zdrojový adresář Rust, předvyplněný Workerem Hello World.

Jakmile vytvoříte svůj první Worker, spusťte wrangler dev příkaz pro spuštění lokálního serveru k vývoji Workeru. Díky tomu budete moci Worker testovat už během vývoje.

npx wrangler dev

Pokud jste Wrangler předtím nepoužili, pokusí se otevřít webový prohlížeč k přihlášení pomocí vašeho účtu Cloudflare.

Přejděte na http://localhost:8787 ↗ a podívejte se na běžící Worker. Jakákoli změna v kódu spustí nové sestavení a po obnovení stránky uvidíte aktuální výstup vašeho Workeru.

Jakmile máte nový projekt vygenerovaný, napište kód svého Workeru. Vstupní bod Workeru najdete v src/lib.rs:

use worker::*;

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

workers-rs poskytuje runtime API, které se téměř shoduje s JavaScript API Workeru, a umožňuje integraci s platformními funkcemi Workeru. Podrobnou dokumentaci k tomuto API najdete v docs.rs/worker ↗.

Toto makro umožňuje definovat entrypointy vašeho Workeru. event makro podporuje následující události:

• fetch - Vyvoláno příchozím požadavkem HTTP.
• scheduled - Vyvoláno Cron Triggers.
• queue - Vyvoláno dávkami příchozích zpráv z Queues (Vyžaduje queue funkci v Cargo.toml, viz workers-rs GitHub repozitář a queues příznak funkce ↗).
• start - Vyvoláno při prvním spuštění Workeru (například pro instalaci panic hooks).

fetch handler poskytuje tři argumenty, které odpovídají JavaScript API:

1. Request ↗

Objekt reprezentující příchozí požadavek. Zahrnuje metody pro přístup k hlavičkám, metodě, cestě, vlastnostem Cloudflare a tělu (s podporou asynchronního streamování a deserializace JSON pomocí Serde ↗).

2. Env ↗

Poskytuje přístup k Worker vazby.

• Secret ↗ - Hodnota secret nakonfigurovaná v dashboardu Cloudflare nebo pomocí wrangler secret put.
• Var ↗ - Proměnná prostředí definovaná v wrangler.toml.
• KvStore ↗ - Workers KV vazba na namespace.
• ObjectNamespace ↗ - Durable Object binding.
• Fetcher ↗ - Service binding na jiný Worker.
• Bucket ↗ - R2 vazba na Bucket.
• D1Database ↗ - D1 databázová vazba.
• Queue ↗ - Queues producer binding.
• Ai ↗ - Workers AI binding.
• Hyperdrive ↗ - Hyperdrive binding.
• AnalyticsEngineDataset ↗ - Analytics Engine binding.
• DynamicDispatcher ↗ - Dynamic Dispatch binding.
• SecretStore ↗ - Secrets Store binding.
• RateLimiter ↗ - Rate Limiting binding.

3. Context ↗

Poskytuje přístup k waitUntil (odložené asynchronní úlohy) a passThroughOnException funkce (fail open).

fetch handler očekává Response ↗ návratový typ, který zahrnuje podporu asynchronního streamování odpovědí klientovi. Jde také o návratový typ všech podpožadavků odeslaných z vašeho Workeru. K dispozici jsou metody pro přístup ke stavovému kódu a hlavičkám i pro asynchronní streamování těla nebo deserializaci z JSON pomocí Serde ↗.

Poskytuje pohodlné API pro směrování ↗ pro obsluhu více cest z jednoho Workeru. Podívejte se na Router příklad v worker-rs GitHub repozitář ↗.

Jakmile máte projekt nakonfigurovaný, můžete Worker nasadit na *.workers.dev subdoména, nebo Custom Domain, pokud máte nějakou nakonfigurovanou. Pokud jste nenakonfigurovali žádnou subdoménu ani doménu, Wrangler vás během nasazování vyzve k jejímu nastavení.

npx wrangler deploy

Zobrazte náhled svého Workeru na adrese <YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev.

Po dokončení těchto kroků budete mít nasazený základní Worker založený na Rustu. Odtud můžete přidávat závislosti a psát kód v Rustu pro implementaci vaší aplikace Worker. Pokud vás zajímá, jak přesně Workers podporují Rust zkompilovaný do Wasm, další část popisuje příslušné knihovny a nástroje.

Wasm Workery jsou spouštěny ze vstupního skriptu JavaScriptu, který se automaticky vytvoří při použití workers-rs.

Aby měly Wasm Workers přístup k funkcím platformy, jako jsou bindings, musí mít přístup k metodám z JavaScript runtime API.

Této interoperability je dosaženo pomocí wasm-bindgen ↗, který poskytuje propojovací kód potřebný k importu runtime API do modulu Wasm a exportu obslužných rutin událostí z něj. wasm-bindgen také poskytuje js-sys ↗, které implementuje typy pro práci s objekty JavaScriptu. V praxi jde o implementační detail, protože workers-rs's API handles conversion to and from JavaScript objects, and interaction with imported JavaScript runtime APIs for you.

wasm-bindgen-futures ↗ (součást wasm-bindgen projekt) poskytuje interoperabilitu mezi Rust Futures a JavaScript Promises. workers-rs vyvolá celou funkci event handleru pomocí spawn_local, což znamená, že můžete programovat pomocí asynchronního Rustu, který se převede na jediný JavaScriptový Promise a spustí se ve smyčce událostí JavaScriptu. Volání importovaných runtime API JavaScriptu se automaticky převádějí na Rust Futures, které lze volat z asynchronních funkcí Rustu.

Chcete-li výsledný binární soubor Wasm spustit na Workers, workers-rs zahrnuje nástroj pro sestavení nazvaný worker-build ↗ které:

1. Vytvoří JavaScriptový vstupní skript (entrypoint), který správně vyvolá modul pomocí wasm-bindgen's JavaScript API.
2. Vyvolá web-pack k minifikaci a sbalení JavaScript kódu.
3. Vytvoří adresářovou strukturu, kterou Wrangler může použít k zabalení a nasazení finálního Workeru.

worker-build se ve výchozím nastavení vyvolává v projektu šablony pomocí vlastního sestavovacího příkazu zadaného v wrangler.toml .

Neoptimalizované binární soubory Rust Wasm mohou být velké a mohou překročit limity velikosti balíčku Workeru nebo mít dlouhou dobu spouštění. Šablonový projekt má předem nakonfigurováno několik užitečných optimalizací velikosti ve vašem Cargo.toml soubor:

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

Nakonec worker-bundle automaticky vyvolává wasm-opt ↗ k další optimalizaci velikosti binárního souboru před nahráním.

• Rust Wasm Book ↗