Antigravity Agent
302 lines
7.1 KiB
Markdown
302 lines
7.1 KiB
Markdown
---
|
|
id: frontend-wasm-integration
|
|
title: WebAssembly — Rust / Go / 통합
|
|
category: Coding
|
|
status: draft
|
|
source_trust_level: B
|
|
verification_status: conceptual
|
|
created_at: 2026-05-09
|
|
updated_at: 2026-05-09
|
|
tags: [frontend, wasm, rust, vibe-coding]
|
|
tech_stack: { language: "Rust / Go / TS", applicable_to: ["Frontend", "Backend"] }
|
|
applied_in: []
|
|
aliases: [WASM, WebAssembly, Rust wasm-bindgen, AssemblyScript, Wasmer, WIT]
|
|
---
|
|
|
|
# WebAssembly
|
|
|
|
> JS 안 빠른 / native lib 사용. **Rust + wasm-bindgen 표준**. ML inference, image / video 처리, crypto, parser, regex. Browser + Node + Cloudflare Workers + WASI.
|
|
|
|
## 📖 핵심 개념
|
|
- WASM: Binary instruction format.
|
|
- wasm-bindgen: Rust ↔ JS 자동 binding.
|
|
- WASI: WASM 의 system interface (file, network).
|
|
- WIT (WebAssembly Interface Types): cross-language.
|
|
|
|
## 💻 코드 패턴
|
|
|
|
### Rust → WASM
|
|
```bash
|
|
# Setup
|
|
cargo new --lib my-wasm
|
|
cd my-wasm
|
|
```
|
|
|
|
```toml
|
|
# Cargo.toml
|
|
[package]
|
|
name = "my-wasm"
|
|
version = "0.1.0"
|
|
edition = "2021"
|
|
|
|
[lib]
|
|
crate-type = ["cdylib"]
|
|
|
|
[dependencies]
|
|
wasm-bindgen = "0.2"
|
|
serde = { version = "1", features = ["derive"] }
|
|
serde-wasm-bindgen = "0.6"
|
|
```
|
|
|
|
```rust
|
|
// src/lib.rs
|
|
use wasm_bindgen::prelude::*;
|
|
use serde::{Serialize, Deserialize};
|
|
|
|
#[wasm_bindgen]
|
|
pub fn fibonacci(n: u32) -> u64 {
|
|
let mut a: u64 = 0; let mut b: u64 = 1;
|
|
for _ in 0..n { let c = a + b; a = b; b = c; }
|
|
a
|
|
}
|
|
|
|
#[derive(Serialize, Deserialize)]
|
|
pub struct Stats { mean: f64, stddev: f64 }
|
|
|
|
#[wasm_bindgen]
|
|
pub fn analyze(data: &[f64]) -> JsValue {
|
|
let mean = data.iter().sum::<f64>() / data.len() as f64;
|
|
let variance = data.iter().map(|x| (x - mean).powi(2)).sum::<f64>() / data.len() as f64;
|
|
serde_wasm_bindgen::to_value(&Stats { mean, stddev: variance.sqrt() }).unwrap()
|
|
}
|
|
```
|
|
|
|
### Build
|
|
```bash
|
|
# wasm-pack
|
|
cargo install wasm-pack
|
|
wasm-pack build --target web
|
|
|
|
# 또는 bundler 통합
|
|
wasm-pack build --target bundler
|
|
|
|
# Output: pkg/ folder with .wasm + JS glue
|
|
```
|
|
|
|
### Use (browser)
|
|
```ts
|
|
import init, { fibonacci, analyze } from './pkg/my_wasm';
|
|
|
|
await init(); // load .wasm
|
|
|
|
console.log(fibonacci(50)); // 12586269025
|
|
console.log(analyze([1.0, 2.0, 3.0])); // { mean: 2, stddev: 0.816 }
|
|
```
|
|
|
|
### Vite plugin
|
|
```ts
|
|
// vite.config.ts
|
|
import wasm from 'vite-plugin-wasm';
|
|
import topLevelAwait from 'vite-plugin-top-level-await';
|
|
|
|
plugins: [wasm(), topLevelAwait()];
|
|
```
|
|
|
|
```ts
|
|
import init, { fibonacci } from './my_wasm';
|
|
await init();
|
|
```
|
|
|
|
### Use case 1: Image processing
|
|
```rust
|
|
#[wasm_bindgen]
|
|
pub fn blur(data: &[u8], width: u32, height: u32, radius: u32) -> Vec<u8> {
|
|
// Gaussian blur
|
|
let img = image::RgbaImage::from_raw(width, height, data.to_vec()).unwrap();
|
|
image::imageops::blur(&img, radius as f32).into_raw()
|
|
}
|
|
```
|
|
|
|
```ts
|
|
const ctx = canvas.getContext('2d')!;
|
|
const imageData = ctx.getImageData(0, 0, w, h);
|
|
const blurred = blur(imageData.data, w, h, 5);
|
|
ctx.putImageData(new ImageData(new Uint8ClampedArray(blurred), w, h), 0, 0);
|
|
```
|
|
|
|
### ML inference (ONNX Runtime Web)
|
|
```ts
|
|
import * as ort from 'onnxruntime-web';
|
|
|
|
const session = await ort.InferenceSession.create('/model.onnx');
|
|
const tensor = new ort.Tensor('float32', input, [1, 3, 224, 224]);
|
|
const result = await session.run({ input: tensor });
|
|
```
|
|
|
|
→ ResNet / YOLO 같은 모델 browser 안.
|
|
|
|
### Transformers.js
|
|
```ts
|
|
import { pipeline } from '@xenova/transformers';
|
|
|
|
const pipe = await pipeline('text-classification', 'Xenova/distilbert-base-uncased-finetuned-sst-2-english');
|
|
const out = await pipe('I love this!');
|
|
// [{ label: 'POSITIVE', score: 0.999 }]
|
|
```
|
|
|
|
→ Hugging Face 모델 browser 직접.
|
|
|
|
### TensorFlow.js (WebGL / WebGPU)
|
|
```ts
|
|
import * as tf from '@tensorflow/tfjs';
|
|
|
|
const model = await tf.loadLayersModel('/model.json');
|
|
const tensor = tf.tensor(input).reshape([1, 224, 224, 3]);
|
|
const pred = model.predict(tensor) as tf.Tensor;
|
|
```
|
|
|
|
### SQLite — sql.js / wasm-sqlite
|
|
```ts
|
|
import initSqlJs from 'sql.js';
|
|
|
|
const SQL = await initSqlJs({ locateFile: f => `/sql-wasm.wasm` });
|
|
const db = new SQL.Database();
|
|
db.run('CREATE TABLE users (id INTEGER, name TEXT)');
|
|
db.run('INSERT INTO users VALUES (?, ?)', [1, 'Alice']);
|
|
const result = db.exec('SELECT * FROM users');
|
|
```
|
|
|
|
→ Browser 안 SQLite.
|
|
|
|
### Worker + WASM (offload main thread)
|
|
```ts
|
|
// worker.ts
|
|
import init, { heavyWork } from './my_wasm';
|
|
|
|
self.onmessage = async (e) => {
|
|
await init();
|
|
const result = heavyWork(e.data);
|
|
self.postMessage(result);
|
|
};
|
|
|
|
// main.ts
|
|
const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' });
|
|
worker.postMessage(input);
|
|
worker.onmessage = (e) => console.log(e.data);
|
|
```
|
|
|
|
### WASI (server-side WASM)
|
|
```bash
|
|
# Wasmer / Wasmtime / Wasmer Edge
|
|
wasmer run my-app.wasm
|
|
```
|
|
|
|
```ts
|
|
// Cloudflare Workers + WASM
|
|
import wasmModule from './my_wasm.wasm';
|
|
|
|
export default {
|
|
async fetch(req: Request): Promise<Response> {
|
|
const instance = await WebAssembly.instantiate(wasmModule);
|
|
return new Response(instance.exports.process(req));
|
|
},
|
|
};
|
|
```
|
|
|
|
### Component model (WIT)
|
|
```wit
|
|
// component.wit
|
|
interface processor {
|
|
process: func(input: list<u8>) -> list<u8>
|
|
}
|
|
```
|
|
|
|
→ Cross-language WASM components.
|
|
|
|
### Performance vs JS
|
|
```
|
|
간단 작업 (sum, fib): JS engine 도 빠름 — WASM 비슷
|
|
복잡 / 메모리 intensive (image, ML, parser): WASM 5-50x 빠름
|
|
SIMD 가능: WASM 더 빠름
|
|
GC 객체 (string, array): JS ↔ WASM boundary 비용
|
|
```
|
|
|
|
→ Hot path + 큰 데이터 = WASM. 일반 = JS.
|
|
|
|
### Bundle size
|
|
```
|
|
Rust + wasm-bindgen: 100KB-1MB 일반
|
|
+ Streaming compile (instantiateStreaming) — 빠른 load
|
|
|
|
wasm-opt 로 size 줄이기.
|
|
```
|
|
|
|
### AssemblyScript (TS-like → WASM)
|
|
```ts
|
|
// Rust 보다 친숙. 단 ecosystem 작음.
|
|
export function fibonacci(n: i32): i64 {
|
|
let a: i64 = 0, b: i64 = 1;
|
|
for (let i = 0; i < n; i++) { const c = a + b; a = b; b = c; }
|
|
return a;
|
|
}
|
|
```
|
|
|
|
### 디버그
|
|
```ts
|
|
// wasm-bindgen — console.log
|
|
import { console_log } from 'wasm-bindgen';
|
|
|
|
console_log!("debug"); // browser DevTools
|
|
```
|
|
|
|
```rust
|
|
#[wasm_bindgen]
|
|
extern "C" {
|
|
#[wasm_bindgen(js_namespace = console)]
|
|
fn log(s: &str);
|
|
}
|
|
log("from rust");
|
|
```
|
|
|
|
### Build size + perf flags
|
|
```toml
|
|
[profile.release]
|
|
opt-level = "z" # size (또는 3 = speed)
|
|
lto = true
|
|
codegen-units = 1
|
|
```
|
|
|
|
```bash
|
|
wasm-opt -Oz -o optimized.wasm input.wasm
|
|
```
|
|
|
|
## 🤔 의사결정 기준
|
|
| 작업 | 추천 |
|
|
|---|---|
|
|
| Browser ML | Transformers.js / ONNX Runtime Web |
|
|
| 이미지 처리 (blur, resize) | Rust + wasm-bindgen |
|
|
| Crypto / hashing | WASM |
|
|
| SQL in browser | sql.js |
|
|
| Edge function (CF Workers) | WASM 가능 |
|
|
| 일반 logic | JS — overhead 안 worth |
|
|
|
|
## ❌ 안티패턴
|
|
- **작은 작업 WASM**: JS-WASM boundary 비용 > 절약.
|
|
- **Streaming compile 안 함**: 큰 .wasm 늦은 load.
|
|
- **Memory copy 매 호출**: 큰 data — typed array share.
|
|
- **Single-thread WASM main**: UI block. Worker.
|
|
- **WASM bundle 분리 X**: 첫 load 큼. Dynamic import.
|
|
- **Debug build prod**: 5-10x 큰. release.
|
|
- **JS-WASM circular call**: stack / boundary 비용.
|
|
|
|
## 🤖 LLM 활용 힌트
|
|
- Rust + wasm-bindgen + wasm-pack = 표준.
|
|
- Vite plugin-wasm + top-level-await.
|
|
- Worker 안 WASM + transferable data.
|
|
- Hot path / 큰 data 만.
|
|
|
|
## 🔗 관련 문서
|
|
- [[Web_OffMain_WebWorker]]
|
|
- [[Perf_V8_Optimization]]
|
|
- [[AI_Local_LLM_Inference]]
|