Rust WASM: CLI를 브라우저로 포팅하기

Rust CLI 도구를 WebAssembly로 마이그레이션하고 GitLab Pages에 배포하기

텍스트 예측을 생성하는 콘솔 애플리케이션이 Rust를 사용하여 WebAssembly로 포팅되었습니다. 계산 로직은 WASM 모듈에 분리되어 있으며, 인터페이스는 터미널과 유사한 사용자 경험을 제공하는 정적 HTML 페이지로 구현되었습니다. GitLab Pages를 통한 배포로 설치 없이 즉시 데모에 접근할 수 있습니다.

이 프로젝트는 핵심 로직을 위한 Rust 라이브러리, 바닐라 JavaScript와 CSS로 구축된 프론트엔드, wasm-pack 아티팩트를 포함합니다. 이 접근 방식은 파일 시스템 접근이나 플랫폼별 API가 필요 없는 경량 유틸리티에 이상적입니다.

프로젝트 아키텍처

구조는 세 가지 구성 요소로 나뉩니다:

• src/lib.rs — 내보낸 함수가 포함된 Rust 핵심 로직.
• public/index.html, styles.css, app.js — 터미널 스타일 인터페이스.
• public/pkg/ — 컴파일된 WASM 파일과 JavaScript 래퍼.

운영 체제 의존성이 없어 포팅이 간단합니다: 애플리케이션은 명령을 받아 텍스트를 반환합니다.

Rust를 WASM으로 내보내기

주요 함수는 #[wasm_bindgen]을 사용하여 내보내집니다:

#[wasm_bindgen]
pub fn generate_reading_text() -> String {
    // 결과 생성 및 포맷팅
}

다음 명령으로 빌드합니다:

wasm-pack build --target no-modules --release --out-dir public/pkg

결과: iching_wasm.js와 iching_wasm_bg.wasm. --target no-modules 옵션은 번들러 없이 통합을 단순화합니다.

브라우저에 WASM 통합하기

app.js에서 모듈은 file://와 작동하도록 base64로 내장된 WASM과 함께 동기적으로 로드됩니다:

const wasmBytes = base64ToBytes(window.ICHING_WASM_BASE64);
wasm_bindgen.initSync({ module: wasmBytes });

const text = wasm_bindgen.generate_reading_text();
output.textContent = text;

index.html에는 다음이 포함됩니다:

• ./pkg/iching_wasm.js — 런타임.
• ./pkg/iching_wasm_bg_base64.js — Base64 WASM.
• app.js — UI 로직.

JavaScript가 WASM을 호출하고 결과가 DOM에 렌더링됩니다.

터미널 스타일 UI

프레임워크 없는 인터페이스:

• 테두리와 창 제목이 있는 컨테이너.
• 고정폭 글꼴 (예: JetBrains Mono).
• 녹색 텍스트가 있는 다크 테마.
• 출력을 위한 <pre>.
• ./generate_reading과 같은 명령을 위한 입력.

시각적 및 행동적으로 콘솔을 모방합니다. 버튼이 WASM 호출을 트리거합니다.

빌드 및 배포를 위한 CI/CD

.gitlab-ci.yml이 프로세스를 자동화합니다:

image: rust:slim

create-pages:
  pages:
    publish: public
  rules:
    - if: '$CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH'
  before_script:
    - rustup target add wasm32-unknown-unknown
    - cargo install wasm-pack --locked
  script:
    - wasm-pack build --target no-modules --release --out-dir public/pkg
    - b64="$(base64 public/pkg/iching_wasm_bg.wasm | tr -d '\n')"
    - printf 'window.ICHING_WASM_BASE64 = "%s";\n' "$b64" > public/pkg/iching_wasm_bg_base64.js

단계: 타겟 설치, wasm-pack으로 빌드, WASM을 base64로 인코딩, public/을 Pages에 게시.

이 접근 방식의 장점

• 접근성: 데모가 Rust나 로컬 설치 없이 모든 브라우저에서 작동합니다.
• 보안: WASM 격리로 네이티브 코드의 위험을 제거합니다.
• 단순성: 정적 호스팅, 하나의 CI 작업.
• 이식성: 시스템 호출이 없는 CLI 도구에 적합합니다.

핵심 요약

• 파일 시스템이나 API 의존성이 없는 로직은 WASM에 완벽하게 맞습니다 — 몇 초 만에 빌드됩니다.
• WASM의 Base64 내장으로 CORS와 file:// 문제를 해결합니다.
• GitLab Pages + wasm-pack CI는 프로토타입을 위한 완성된 파이프라인을 제공합니다.
• UI를 위한 바닐라 JavaScript/HTML로 오버헤드를 최소화합니다.
• #[wasm_bindgen]은 Rust를 JavaScript로 내보내는 표준입니다.

— Editorial Team