Rust

Cloudflare Workersは、workers-rsクレート ↗を介してRustをサポートしており、Runtime APIsやbindingsを、Workers KV、R2、Queuesなどの開発者プラットフォーム製品に直接Rustコードから利用できるようにします。

このガイドに従うことで、Rustプログラミング言語で完全にWorkerを構築する方法を学ぶことができます。

前提条件

このガイドを始める前に、以下を確認してください：

• 最近のバージョンのRust ↗
• npm ↗
• Rust wasm32-unknown-unknownツールチェーン：

rustup target add wasm32-unknown-unknown

• そして、次のコマンドを実行してcargo-generateサブコマンドをインストールします：

cargo install cargo-generate

1. Wranglerで新しいプロジェクトを作成する

ターミナルウィンドウを開き、次のコマンドを実行してRustでWorkerプロジェクトテンプレートを生成します：

cargo generate cloudflare/workers-rs

あなたのプロジェクトは、あなたが名付けた新しいディレクトリに作成され、以下のファイルとフォルダが見つかります：

• Cargo.toml - RustのCargo ↗パッケージマネージャーの標準プロジェクト設定ファイル。テンプレートは、Workers上でWasmをビルドするためのベストプラクティス設定を事前に入力しています。
• wrangler.toml - Wranglerの設定ファイルで、worker-buildを呼び出すカスタムビルドコマンドが事前に入力されています（Wrangler Bundlingを参照）。
• src - Rustのソースディレクトリで、Hello World Workerが事前に入力されています。

2. ローカルで開発する

最初のWorkerを作成したら、wrangler devコマンドを実行して、Workerの開発用ローカルサーバーを起動します。これにより、開発中にWorkerをテストできます。

npx wrangler dev

Wranglerを初めて使用する場合は、Cloudflareアカウントでログインするためにウェブブラウザを開こうとします。

ノート

このステップで問題が発生した場合やブラウザインターフェースにアクセスできない場合は、wrangler loginのドキュメントを参照してください。

http://localhost:8787 ↗にアクセスして、実行中のWorkerを確認します。コードに加えた変更は再ビルドをトリガーし、ページをリロードするとWorkerの最新の出力が表示されます。

3. Workerコードを書く

新しいプロジェクトが生成されたら、Workerコードを書きます。src/lib.rsでWorkerのエントリポイントを見つけます：

use worker::*;

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

ノート

ここにはいくつかの直感に反する動作があります：

1. workers-rsは、JavaScript Workersで見られるのと同じ関数シグネチャを期待するeventマクロを提供します。
2. asyncは一般的にWasmでサポートされていませんが、workers-rsプロジェクトではasyncを使用できます（asyncを参照）。

関連するランタイムAPI

workers-rsは、WorkerのJavaScript APIに密接に一致するランタイムAPIを提供し、Workerのプラットフォーム機能との統合を可能にします。APIの詳細なドキュメントについては、docs.rs/worker ↗を参照してください。

eventマクロ

このマクロを使用すると、Workerのエントリポイントを定義できます。eventマクロは以下のイベントをサポートしています：

• fetch - 受信したHTTPリクエストによって呼び出されます。
• scheduled - Cron Triggersによって呼び出されます。
• queue - Queuesからの受信メッセージバッチによって呼び出されます（Cargo.tomlでqueue機能が必要です。workers-rs GitHubリポジトリとqueues機能フラグ ↗を参照）。
• start - Workerが最初に起動されたときに呼び出されます（たとえば、パニックフックをインストールするため）。

fetchパラメータ

fetchハンドラーは、JavaScript APIに一致する3つの引数を提供します：

1. Request ↗

受信リクエストを表すオブジェクト。これには、ヘッダー、メソッド、パス、Cloudflareプロパティ、およびボディにアクセスするためのメソッドが含まれています（非同期ストリーミングとJSONデシリアライズをサポートしていますSerde ↗を使用）。

2. Env ↗

Workerのbindingsにアクセスを提供します。

• Secret ↗ - Cloudflareダッシュボードで設定された秘密値、またはwrangler secret putを使用して設定されたもの。
• Var ↗ - wrangler.tomlで定義された環境変数。
• KvStore ↗ - WorkersのKV名前空間バインディング。
• ObjectNamespace ↗ - Durable Objectバインディング。
• Fetcher ↗ - 別のWorkerへのService binding。
• Bucket ↗ - R2バケットバインディング。

3. Context ↗

waitUntil（遅延非同期タスク）およびpassThroughOnException（失敗オープン）機能へのアクセスを提供します。

Response ↗

fetchハンドラーは、Response ↗戻り値の型を期待しており、クライアントへのストリーミングレスポンスを非同期でサポートしています。これは、Workerから行われるサブリクエストの戻り値の型でもあります。ステータスコードやヘッダーにアクセスするためのメソッドがあり、ボディを非同期でストリーミングしたり、Serde ↗を使用してJSONからデシリアライズしたりできます。

Router

1つのWorkerから複数のパスを提供する便利なルーティングAPI ↗を実装します。worker-rs GitHubリポジトリのRouterの例 ↗を参照してください。

4. Workerプロジェクトをデプロイする

プロジェクトが設定されたので、Workerを*.workers.devサブドメインまたは設定されたカスタムドメインにデプロイできます。サブドメインやドメインを設定していない場合、Wranglerはデプロイプロセス中に設定するように促します。

npx wrangler deploy

<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.devでWorkerをプレビューします。

ノート

最初に*.workers.devサブドメインにプッシュすると、DNSが伝播する間に523エラーが表示されることがあります。これらのエラーは、1分ほどで解決されるはずです。

これらのステップを完了すると、基本的なRustベースのWorkerがデプロイされます。ここから、クレートの依存関係を追加し、Rustでコードを書いてWorkerアプリケーションを実装できます。RustがWasmにコンパイルされてWorkersによってサポートされる仕組みについてもっと知りたい場合は、次のセクションで関与するライブラリとツールについて説明します。

このデプロイメントの仕組み

Wasm Workersは、workers-rsを使用すると自動的に作成されるJavaScriptエントリポイントスクリプトから呼び出されます。

JavaScriptプラミング (wasm-bindgen)

バインディングなどのプラットフォーム機能にアクセスするために、Wasm WorkersはJavaScriptランタイムAPIのメソッドにアクセスできる必要があります。

この相互運用性は、wasm-bindgen ↗を使用して実現されており、ランタイムAPIをインポートし、Wasmモジュールからイベントハンドラーをエクスポートするために必要なグルーコードを提供します。wasm-bindgenはまた、JavaScriptオブジェクトと対話するための型を実装するjs-sys ↗も提供します。実際には、これは実装の詳細であり、workers-rsのAPIがJavaScriptオブジェクトとの変換や、インポートされたJavaScriptランタイムAPIとの対話を処理します。

ノート

workers-rs / worker-buildなしでwasm-bindgenを使用している場合、生成されるJavaScriptをパッチする必要があります。これは、Workersでwasmファイルをインポートすると、パフォーマンスとセキュリティの理由からWebAssembly.Moduleが得られるためです。

wasm-bindgenが生成するJavaScriptをパッチするには：

1. 通常通りwasm-pack build --target bundlerを実行します。
2. 生成されたJavaScriptファイルをパッチします（以下のコードブロックはファイル名がmywasmlib.jsであると仮定しています）：

import * as imports from "./mywasmlib_bg.js";

// nodeとworkerdの両方の構文を切り替えます
import wkmod from "./mywasmlib_bg.wasm";
import * as nodemod from "./mywasmlib_bg.wasm";
if (typeof process !== "undefined" && process.release.name === "node") {
  imports.__wbg_set_wasm(nodemod);
} else {
  const instance = new WebAssembly.Instance(wkmod, {
    "./mywasmlib_bg.js": imports,
  });
  imports.__wbg_set_wasm(instance.exports);
}

export * from "./mywasmlib_bg.js";

3. Workerエントリポイントで、関数をインポートして直接使用します：

import { myFunction } from "path/to/mylib.js";

Async (wasm-bindgen-futures)

wasm-bindgen-futures ↗（wasm-bindgenプロジェクトの一部）は、RustのFutureとJavaScriptのPromise間の相互運用性を提供します。workers-rsは、全体のイベントハンドラー関数をspawn_localを使用して呼び出すため、非同期Rustでプログラムを作成でき、これは単一のJavaScript Promiseに変換され、JavaScriptのイベントループで実行されます。インポートされたJavaScriptランタイムAPIへの呼び出しは、自動的に非同期Rust関数から呼び出すことができるRust Futuresに変換されます。

バンドル (worker-build)

生成されたWasmバイナリをWorkersで実行するために、workers-rsにはworker-build ↗というビルドツールが含まれています：

1. wasm-bindgenのJavaScript APIを使用してモジュールを適切に呼び出すJavaScriptエントリポイントスクリプトを作成します。
2. web-packを呼び出してJavaScriptコードを最小化およびバンドルします。
3. Wranglerが最終的なWorkerをバンドルおよびデプロイするために使用できるディレクトリ構造を出力します。

worker-buildは、wrangler.tomlで指定されたカスタムビルドコマンドを使用して、テンプレートプロジェクトでデフォルトで呼び出されます。

バイナリサイズ (wasm-opt)

最適化されていないRust Wasmバイナリは大きくなる可能性があり、Workerのバンドルサイズ制限を超えたり、起動時間が長くなったりすることがあります。テンプレートプロジェクトは、Cargo.tomlファイルにいくつかの便利なサイズ最適化を事前に設定しています：

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

最後に、worker-bundleは、アップロード前にバイナリサイズをさらに最適化するためにwasm-opt ↗を自動的に呼び出します。

関連リソース

• Rust Wasm Book ↗