rust-with-typescript

문제

TypeScript 개발자가 Rust를 배울 때는 새로운 문법보다 소유권, borrowing과 lifetime을 기존의 사고방식과 연결하는 일이 어려웠습니다. 익숙한 코드를 Rust와 나란히 비교하고, 컴파일 결과를 설명 바로 옆에서 확인할 수 있는 학습 환경을 만들었습니다.

브라우저에서 코드를 실행하게 하면 문서 사이트가 실행 서버의 진입점이 됩니다. 학습용 예제를 편하게 실행하는 경험과 서버에 들어오는 요청을 제한하는 경계를 함께 설계해야 했습니다.

선택한 방법

14개 챕터를 TypeScript의 개념에서 시작

Astro와 Starlight로 한국어·영어 문서를 구성했습니다. 각 챕터에 TypeScript와 Rust 예제를 나란히 배치하고, 소유권·borrowing, enum과 pattern matching, trait, 오류 처리와 비동기를 단계적으로 연결했습니다. 문법을 번역하는 대신 같은 문제를 두 타입 시스템에서 어떻게 표현하는지 비교하도록 했습니다.

문서 화면과 Rust 실행 서버를 분리

문서와 실행 API는 Cloudflare Workers에, Rust/Axum 실행 서버는 별도 서비스에 두었습니다. 코드 블록의 실행 버튼은 API를 거쳐 실행 서버를 호출하고 stdout, stderr, 종료 코드와 실행 시간을 문서 안에 표시합니다. 성공 출력뿐 아니라 컴파일 오류도 같은 학습 흐름에서 볼 수 있도록 했습니다.

문서에 포함된 예제만 실행하도록 검증

빌드할 때 실행 가능한 코드의 SHA-256 허용 목록을 생성합니다. API는 요청을 정규화해 이 목록과 대조하고, 문서에 없는 코드는 실행 서버로 전달하기 전에 거부합니다. 임의 코드 입력기 대신 설명에 포함된 예제를 실행하는 제품 범위에 맞춘 선택입니다.

실행 서버에는 동시 컴파일 수, IP별 요청 빈도와 컴파일·실행 타임아웃을 두었습니다. 실행마다 별도의 임시 디렉터리를 사용하고 출력 길이도 제한했습니다. 프런트엔드는 실행 서버의 실패를 API 오류로 받아 결과 영역에 표시합니다.

문서와 실행 코드의 검증·배포를 연결

CI에서 Astro 타입 검사·빌드와 Rust clippy·테스트를 분리해 실행합니다. main 변경은 Workers 배포로 이어지고, 배포가 끝나면 태그와 변경 내역을 포함한 GitHub Release를 생성하도록 구성했습니다.

확인한 결과

한국어·영어 14개 챕터와 문서 내 Rust 예제 실행 흐름을 구현해 배포했습니다. 문서 사이트는 Workers 주소로 공개되어 있으며, 소스와 배포·릴리스 기록을 함께 확인할 수 있습니다.

콘텐츠 제작뿐 아니라 문서 예제의 빌드 시점 검증, 실행 API와 Rust 서버의 역할 분리, 결과 표시와 배포 자동화까지 연결한 프로젝트입니다.