spinny:~/writing $ vim webassembly-wasm-complete-guide.md
1~2WebAssembly (WASM) به عنوان راهی برای اجرای C++ در مرورگر آغاز شد. در سال 2026، همه جا اجرا میشود - مرورگرها، سرورها، شبکههای لبه، دستگاههای تعبیهشده - و برخی از پرتقاضاترین اپلیکیشنهای وب را تامین میکند. موتور رندر Figma، Adobe Photoshop روی وب، پردازش ویدیوی Google Meet، و پلتفرم محاسبات لبه Cloudflare همگی روی WebAssembly اجرا میشوند.3~4طبق Chrome Platform Status، WASM در اوایل 2026 حدود 5.5% از تمام بارگذاریهای صفحات Chrome را تشکیل میدهد، که از 4.5% سال قبل افزایش یافته است. با تبدیل شدن WASM 3.0 به استاندارد W3C و بلوغ WASI به سمت نسخه 1.0، اکوسیستم به نقطه عطفی رسیده است.5~6این راهنما همه چیزی را که برای شروع ساخت با WebAssembly نیاز دارید پوشش میدهد.7~8## WebAssembly چیست؟9~10WebAssembly یک فرمت دستورالعمل باینری است که به عنوان یک هدف کامپایل طراحی شده است. شما کد را به زبان سطح بالا (Rust, C, C++, Go, Kotlin) مینویسید، آن را به `.wasm` کامپایل میکنید، و در هر محیطی که محیط اجرای WASM دارد اجرا میکنید - مرورگرها، Node.js، Cloudflare Workers، Wasmtime، یا Wasmer.11~12```mermaid13graph LR14 Rust[Rust / C / C++] --> Compiler[Compiler]15 Compiler --> WASM[.wasm Binary]16 WASM --> Browser[Browser V8/SpiderMonkey]17 WASM --> Server[Server Wasmtime]18 WASM --> Edge[Edge Cloudflare Workers]19 WASM --> Embedded[Embedded WAMR]20```21~22### چگونه کار میکند23~24WASM یک **ماشین مجازی مبتنی بر پشته (stack-based virtual machine)** است. توابع مقادیر را روی یک پشته عملوند push و pop میکنند. محیط اجرای میزبان (V8 در Chrome، SpiderMonkey در Firefox) بایتکد WASM را به کد ماشین بومی JIT-کامپایل میکند، به همین دلیل عملکرد نزدیک به بومی است.25~26ویژگیهای کلیدی:27~28- **اجرای ایزوله (Sandboxed execution)**: ماژولهای WASM فقط میتوانند به منابعی دسترسی پیدا کنند که میزبان صراحتاً اعطا میکند. بدون اجازه، نه فایلسیستم، نه شبکه، نه دسترسی به سیستمعامل. این اساساً متفاوت از کد بومی است.29- **حافظه خطی (Linear memory)**: یک `ArrayBuffer` پیوسته واحد که بین WASM و میزبان مشترک است. دادههای پیچیده (رشتهها، ساختارها) با نوشتن در حافظه و اشتراکگذاری اشارهگر منتقل میشوند.30- **محدودیت نوع (Type-limited)**: WASM به صورت بومی فقط از چهار نوع پشتیبانی میکند: `i32`، `i64`، `f32`، `f64`. هر چیز دیگری (رشتهها، آرایهها، اشیا) نیاز به رمزگذاری از طریق حافظه خطی یا Component Model دارد.31- **قابل حمل (Portable)**: همان باینری `.wasm` روی هر پلتفرمی با محیط اجرای WASM، بدون کامپایل مجدد اجرا میشود.32~33### WASM در مقابل JavaScript34~35WASM جایگزین JavaScript نمیشود. مکمل آن است.36~37| جنبه | JavaScript | WebAssembly |38|--------|-----------|-------------|39| **تجزیه** | Parse + compile در زمان اجرا | باینری از پیش کامپایل شده، فقط decode |40| **سرعت اجرا** | بهینهشده با JIT، متغیر | نزدیک به بومی، ثابت |41| **راهاندازی** | سریع برای اسکریپتهای کوچک | decode سریع، قابل پیشبینی |42| **دسترسی DOM** | مستقیم | غیرمستقیم (از طریق کد واسط JS) |43| **بهترین برای** | UI، دستکاری DOM، مدیریت رویداد | محاسبات فشرده CPU |44| **جمعآوری زباله** | داخلی | WasmGC (جدید)، یا دستی |45~46برای کار UI و DOM از JavaScript استفاده کنید. برای محاسبات سنگین از WASM استفاده کنید: پردازش تصویر، رمزگذاری ویدیو، شبیهسازی فیزیک، رمزنگاری، تجزیه داده.47~48## WASM 3.0: چه چیزی جدید است49~50WebAssembly 3.0 در سپتامبر 2025 به استاندارد W3C تبدیل شد و نه ویژگی را که سالها در حال توسعه بودند استاندارد کرد.51~52| ویژگی | چه چیزی را فعال میکند |53|---------|----------------|54| **WasmGC** | جمعآوری زباله بومی در WASM. زبانهای مدیریتشده (Java, Kotlin, Dart) میتوانند بدون ارسال محیط اجرای GC خود به WASM کامپایل شوند. در Chrome 119+، Firefox 120+، Safari 18.2+ پشتیبانی میشود. |55| **Exception Handling** | `try`/`catch` بومی در WASM. قبلاً، استثناها نیاز به رفت و برگشتهای پرهزینه به JavaScript داشتند. |56| **Tail Calls** | بازگشت کارآمد بدون سرریز پشته را فعال میکند. برای زبانهای تابعی حیاتی است. |57| **Relaxed SIMD** | دستورالعملهای بردار 128 بیتی برای پردازش داده موازی. بهینهسازیهای خاص سختافزار را فعال میکند. |58| **Memory64** | محدودیت حافظه خطی 4GB را میشکند. برای پردازش داده در مقیاس بزرگ مورد نیاز است. |59| **Multi-memory** | مناطق حافظه مستقل متعدد در یک ماژول. |60~61تاثیرگذارترین **WasmGC** است. قبل از آن، کامپایل Java یا Kotlin به WASM به معنای ارسال یک جمعکننده زباله کامل به عنوان بخشی از باینری بود که حجم فایلها را بالا میبرد. اکنون GC خود مرورگر مدیریت حافظه را برای ماژولهای WASM انجام میدهد، دقیقاً مانند کاری که برای JavaScript انجام میدهد.62~63## WASI: WebAssembly فراتر از مرورگر64~65WASM در مرورگر قدرتمند است، اما **WASI (رابط سیستم WebAssembly)** چیزی است که WASM را به یک محیط اجرای جهانی تبدیل میکند. WASI رابطهای استاندارد برای منابع سیستم فراهم میکند - فایلها، شبکه، ساعتها، اعداد تصادفی - که اجازه میدهد ماژولهای WASM خارج از مرورگر اجرا شوند.66~67```mermaid68graph TD69 subgraph "Browser"70 B[WASM Module] --> Web[Web APIs\nDOM, Fetch, Canvas]71 end72~73 subgraph "Server / Edge / Embedded"74 S[WASM Module] --> WASI[WASI Interfaces]75 WASI --> FS[wasi:filesystem]76 WASI --> Net[wasi:sockets]77 WASI --> HTTP[wasi:http]78 WASI --> Clock[wasi:clocks]79 WASI --> Rand[wasi:random]80 end81```82~83WASI Preview 2 (نسخه پایدار فعلی) این رابطها را تعریف میکند:84~85- `wasi:filesystem` - عملیات فایل از طریق دستگیرههای قابلیت (نه توصیفکننده فایل سنتی)86- `wasi:sockets` - شبکه TCP/UDP87- `wasi:http` - مدیریت درخواست/پاسخ HTTP88- `wasi:clocks` - ساعت دیواری، ساعت یکنوا89- `wasi:random` - تصادفی رمزنگاری90- `wasi:cli` - آرگومانهای خط فرمان، متغیرهای محیطی، stdio91~92اصل کلیدی **امنیت مبتنی بر قابلیت (capability-based security)** است: یک ماژول WASM نمیتواند به فایلسیستم دسترسی پیدا کند مگر اینکه میزبان صراحتاً یک دستگیره به دایرکتوری خاصی اعطا کند. این WASI را اساساً امنتر از اجرای فایلهای اجرایی بومی میکند.93~94### مسیر به WASI 1.095~96WASI 0.3.0 (افزودن اولیههای async/concurrency) در 2026 انتظار میرود، و WASI 1.0 پس از آن خواهد آمد. افزوده اصلی async یکپارچه با زبان همراه با I/O جریانی بدون کپی است.97~98## Component Model99~100ماژولهای اصلی WASM فقط میتوانند اعداد مبادله کنند. **Component Model** این محدودیت را با افزودن یک سیستم نوع غنی و لایه ترکیبپذیری روی WASM حل میکند.101~102### WIT (انواع رابط WebAssembly)103~104WIT یک زبان تعریف رابط است که به مولفهها اجازه میدهد واردات و صادرات خود را با انواع غنی اعلام کنند - رشتهها، رکوردها، لیستها، متغیرها، شمارشها - نه فقط `i32` و `f64`.105~106```wit107// calculator.wit108package myorg:calculator@1.0.0;109~110interface operations {111 record calculation {112 expression: string,113 result: f64,114 timestamp: u64,115 }116~117 add: func(a: f64, b: f64) -> f64;118 multiply: func(a: f64, b: f64) -> f64;119 history: func() -> list<calculation>;120}121~122world calculator {123 export operations;124}125```126~127زنجیرههای ابزار مانند `wit-bindgen` اتصالات خاص زبان را از فایلهای WIT تولید میکنند. یک مولفه Rust و یک مولفه Python میتوانند از طریق قراردادهای WIT رشتهها، رکوردها و لیستها مبادله کنند بدون اینکه هیچ طرفی زبان پیادهسازی طرف دیگر را بداند.128~129## ساخت اولین ماژول WASM با Rust130~131Rust بالغترین ابزار WASM را دارد. بیایید یک مثال عملی بسازیم: یک ماژول پردازش تصویر که در مرورگر اجرا میشود.132~133### راهاندازی134~135```bash136# Install the WASM target for Rust137rustup target add wasm32-unknown-unknown138~139# Install wasm-pack (builds Rust to WASM + generates JS bindings)140cargo install wasm-pack141~142# Create a new library project143cargo new --lib image-processor144cd image-processor145```146~147### پیکربندی Cargo.toml148~149```toml150[package]151name = "image-processor"152version = "0.1.0"153edition = "2021"154~155[lib]156crate-type = ["cdylib"]157~158[dependencies]159wasm-bindgen = "0.2"160```161~162### نوشتن کد Rust163~164```rust165// src/lib.rs166use wasm_bindgen::prelude::*;167~168/// Convert an image buffer to grayscale.169/// Input: RGBA pixel data as a flat u8 array (4 bytes per pixel).170/// Output: Modified in place for zero-copy performance.171#[wasm_bindgen]172pub fn grayscale(pixels: &mut [u8]) {173 for chunk in pixels.chunks_exact_mut(4) {174 let r = chunk[0] as f32;175 let g = chunk[1] as f32;176 let b = chunk[2] as f32;177 // ITU-R BT.709 luminance coefficients178 let gray = (0.2126 * r + 0.7152 * g + 0.0722 * b) as u8;179 chunk[0] = gray;180 chunk[1] = gray;181 chunk[2] = gray;182 // chunk[3] is alpha, leave unchanged183 }184}185~186/// Adjust brightness of an image.187/// factor > 1.0 brightens, < 1.0 darkens.188#[wasm_bindgen]189pub fn adjust_brightness(pixels: &mut [u8], factor: f32) {190 for chunk in pixels.chunks_exact_mut(4) {191 chunk[0] = ((chunk[0] as f32 * factor).min(255.0)) as u8;192 chunk[1] = ((chunk[1] as f32 * factor).min(255.0)) as u8;193 chunk[2] = ((chunk[2] as f32 * factor).min(255.0)) as u8;194 }195}196~197/// Invert all colors in the image.198#[wasm_bindgen]199pub fn invert(pixels: &mut [u8]) {200 for chunk in pixels.chunks_exact_mut(4) {201 chunk[0] = 255 - chunk[0];202 chunk[1] = 255 - chunk[1];203 chunk[2] = 255 - chunk[2];204 }205}206~207/// Calculate the average brightness of an image (0-255).208#[wasm_bindgen]209pub fn average_brightness(pixels: &[u8]) -> f32 {210 let mut total: f64 = 0.0;211 let pixel_count = pixels.len() / 4;212 for chunk in pixels.chunks_exact(4) {213 let luminance = 0.2126 * chunk[0] as f64214 + 0.7152 * chunk[1] as f64215 + 0.0722 * chunk[2] as f64;216 total += luminance;217 }218 (total / pixel_count as f64) as f32219}220```221~222### ساخت223~224```bash225wasm-pack build --target web226```227~228این یک دایرکتوری `pkg/` تولید میکند با:229- `image_processor_bg.wasm` - باینری WASM کامپایل شده230- `image_processor.js` - کد واسط JavaScript با تعریفات TypeScript231- `package.json` - آماده انتشار در npm232~233### استفاده در JavaScript234~235```html236<!DOCTYPE html>237<html>238<head><title>WASM Image Processor</title></head>239<body>240 <canvas id="canvas" width="800" height="600"></canvas>241 <button onclick="applyGrayscale()">Grayscale</button>242 <button onclick="applyBrightness()">Brighten</button>243 <button onclick="applyInvert()">Invert</button>244~245 <script type="module">246 import init, { grayscale, adjust_brightness, invert } from "./pkg/image_processor.js";247~248 let ctx;249 let imageData;250~251 async function setup() {252 await init();253 const canvas = document.getElementById("canvas");254 ctx = canvas.getContext("2d");255~256 // Load an image onto the canvas257 const img = new Image();258 img.onload = () => {259 ctx.drawImage(img, 0, 0);260 imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);261 };262 img.src = "photo.jpg";263 }264~265 window.applyGrayscale = () => {266 grayscale(imageData.data);267 ctx.putImageData(imageData, 0, 0);268 };269~270 window.applyBrightness = () => {271 adjust_brightness(imageData.data, 1.3);272 ctx.putImageData(imageData, 0, 0);273 };274~275 window.applyInvert = () => {276 invert(imageData.data);277 ctx.putImageData(imageData, 0, 0);278 };279~280 setup();281 </script>282</body>283</html>284```285~286بینش کلیدی: `imageData.data` یک `Uint8ClampedArray` است که توسط یک `ArrayBuffer` پشتیبانی میشود. هنگام ارسال به WASM، همان حافظه را به اشتراک میگذارد - بدون کپی. تابع Rust پیکسلها را در جا تغییر میدهد، و سمت JavaScript بلافاصله تغییرات را میبیند.287~288## سطح پایینتر: نمونهسازی دستی WASM289~290اگر نمیخواهید از `wasm-bindgen` استفاده کنید، میتوانید مستقیماً ماژولهای WASM را نمونهسازی کنید:291~292```javascript293const response = await fetch("calculator.wasm");294const { instance } = await WebAssembly.instantiateStreaming(response, {295 env: {296 // Functions the WASM module can call297 log_result: (value) => console.log("Result:", value),298 },299});300~301// Call exported functions302const { add, multiply } = instance.exports;303console.log(add(5, 3)); // 8304console.log(multiply(4, 7)); // 28305```306~307این زمانی مفید است که حداقل سربار را میخواهید و نیازی به تعامل نوع غنی ندارید.308~309## عملکرد: WASM در مقابل JavaScript310~311معیارهای واقعی تسریع قابل توجهی را برای وظایف فشرده CPU نشان میدهند:312~313| وظیفه | JavaScript | WASM | تسریع |314|------|-----------|------|---------|315| پردازش تصویر 4K | 180ms | 8ms (با SIMD) | 22x |316| تغییر اندازه تصویر (4K) | 250ms | 45ms | 5.5x |317| شبیهسازی فیزیک (10K موجودیت) | افت فریم | 60fps روان | ~10x |318| تجزیه JSON (بار بزرگ) | 12ms | 3ms | 4x |319| هش رمزنگاری | 45ms | 6ms | 7.5x |320~321WASM با حدود 95% سرعت کد بومی اجرا میشود. بزرگترین بهرهها از اینها میآیند:322- عملکرد قابل پیشبینی (بدون گرمشدن JIT، بدون توقفهای GC)323- دستورالعملهای SIMD برای پردازش داده موازی324- دسترسی مستقیم حافظه بدون دخالت جمعکننده زباله325~326جایی که WASM سریعتر نیست: دستکاری DOM، محاسبات کوچک، وظایف محدود به I/O. JavaScript قبلاً برای اینها بهینه شده است.327~328## موارد استفاده پروداکشن329~330### Figma: رندر بردار در زمان واقعی331~332موتور رندر اصلی Figma، C++ کامپایل شده به WASM است. هر شکل، گرادیان و افکت در WASM محاسبه میشود و روی یک عنصر Canvas رسم میشود. این به Figma اجازه میدهد طراحیهای پیچیده با هزاران لایه را با 60fps در مرورگر مدیریت کند - عملکردی که در JavaScript خالص غیرممکن خواهد بود.333~334### Adobe Photoshop روی وب335~336Adobe فیلترها و ابزارهای کلیدی Photoshop را با استفاده از Rust به WASM منتقل کرد. معیارهای آنها پردازش تصویر 4K در 22ms با WASM SIMD در مقابل 180ms در JavaScript را نشان میدهد - بهبود 8 برابری که پیشنمایش فیلتر در زمان واقعی را ممکن میسازد.337~338### Cloudflare Workers339~340Cloudflare ماژولهای WASM را در ایزولههای V8 در بیش از 330 مکان لبه اجرا میکند. راهاندازی سرد 1-5ms است (در مقایسه با 100-500ms برای serverless مبتنی بر کانتینر). در فوریه 2026، آنها استنتاج Llama-3-8b را با استفاده از WASM در سراسر شبکه لبه خود مستقر کردند.341~342### Google Meet343~344تار کردن پسزمینه و پسزمینههای مجازی در Google Meet از WASM با SIMD برای پردازش ویدیو در زمان واقعی استفاده میکنند. ماژول WASM هر فریم ویدیو را به اندازه کافی سریع پردازش میکند تا ویدیوی روان در 30fps حفظ شود.345~346## پشتیبانی مرورگر (2026)347~348| ویژگی | Chrome | Firefox | Safari | Edge |349|---------|--------|---------|--------|------|350| Core WASM | کامل | کامل | کامل | کامل |351| Threads | بله | بله | بله | بله |352| SIMD (128-bit) | بله | بله | بله | بله |353| WasmGC | 119+ | 120+ | 18.2+ | بله |354| Exception Handling | بله | بله | بله | بله |355| Memory64 | بله | بله | جزئی | بله |356~357همه مرورگرهای اصلی WASM را به طور کامل پشتیبانی میکنند. ویژگیهای جدیدتر (WasmGC, Exception Handling) به در دسترس بودن گسترده رسیدهاند.358~359## مرجع ابزارها360~361| ابزار | هدف | نصب |362|------|---------|---------|363| **wasm-pack** | ساخت Rust به WASM، تولید بستههای npm | `cargo install wasm-pack` |364| **wasm-bindgen** | اتصالات تعامل Rust/JS (توسط wasm-pack استفاده میشود) | وابستگی در Cargo.toml |365| **wasm-opt** | بهینهسازی حجم باینری (کاهش 50%+) | بخشی از Binaryen: `brew install binaryen` |366| **wit-bindgen** | تولید اتصالات از فایلهای WIT | `cargo install wit-bindgen-cli` |367| **Wasmtime** | محیط اجرای WASM سمت سرور (پیادهسازی مرجع WASI) | `brew install wasmtime` |368| **Wasmer** | محیط اجرای WASM جایگزین با پشتیبانی WASI | `curl https://get.wasmer.io -sSfL \| sh` |369| **wasm-feature-detect** | تشخیص ویژگی مرورگر در زمان اجرا | `npm install wasm-feature-detect` |370~371### بهینهسازی حجم باینری372~373باینریهای WASM میتوانند بزرگ باشند. روش کوچک کردن آنها:374~375```toml376# Cargo.toml377[profile.release]378opt-level = "z" # Optimize for size379lto = true # Link-time optimization380codegen-units = 1 # Better optimization, slower compile381strip = true # Strip debug symbols382```383~384```bash385# Build in release mode386wasm-pack build --release --target web387~388# Further optimize with wasm-opt389wasm-opt -Oz pkg/image_processor_bg.wasm -o pkg/image_processor_bg.wasm390```391~392یک ماژول معمولی Rust WASM با این بهینهسازیها از 500KB به زیر 50KB کاهش مییابد.393~394## نقشه راه شروع395~396```mermaid397flowchart TD398 A[Week 1: Basics] --> B[Week 2: Real Project]399 B --> C[Week 3: WASI and Server-side]400 C --> D[Month 2+: Production]401~402 A --> A1[Install Rust + wasm-pack]403 A --> A2[Build hello-world WASM module]404 A --> A3[Call WASM functions from JavaScript]405~406 B --> B1[Build image processor or game physics]407 B --> B2[Use wasm-bindgen for rich types]408 B --> B3[Benchmark against pure JS]409~410 C --> C1[Run WASM with Wasmtime]411 C --> C2[Explore WASI interfaces]412 C --> C3[Try Component Model with WIT]413~414 D --> D1[Optimize binary size]415 D --> D2[Use SIMD for parallelism]416 D --> D3[Deploy to Cloudflare Workers or browser]417```418~419## نتیجهگیری420~421WebAssembly دیگر آزمایشی نیست. یک فناوری پروداکشن است که برخی از پرتقاضاترین اپلیکیشنهای وب از آن استفاده میکنند. عملکرد نزدیک به بومی، امنیت ایزوله، و قابلیت حمل جهانی - هیچ هدف کامپایل دیگری هر سه را به شما نمیدهد.422~423نیازی نیست کل اپلیکیشن خود را در WASM بازنویسی کنید. با یک تابع فشرده CPU شروع کنید - یک فیلتر تصویر، یک تجزیهکننده داده، یک محاسبه فیزیک - آن را به WASM کامپایل کنید و از JavaScript فراخوانی کنید. تفاوت را اندازه بگیرید. سپس تصمیم بگیرید WASM کجای دیگر میتواند کمک کند.424~425ابزارها بالغ هستند، پشتیبانی مرورگر جهانی است، و اکوسیستم در حال رشد است. اگر Rust مینویسید، از قبل فقط یک دستور با مرورگر فاصله دارید.426~427> **چکلیست شروع:**428>429> - [x] Rust و wasm-pack نصب شدهاند430> - [x] اولین ماژول WASM ساخته شده و در مرورگر اجرا میشود431> - [x] تعامل JavaScript کار میکند (فراخوانی WASM از JS)432> - [x] بیلد انتشار با بهینهسازیهای حجم اعمال شده433> - [x] عملکرد در مقایسه با معادل JavaScript خالص معیارسنجی شده434> - [x] WASI با Wasmtime برای موارد استفاده سمت سرور بررسی شده435~
NORMAL · webassembly-wasm-complete-guide.md [readonly]435 lines · :q to close