iroh 딥다이브
— 공개키로 전화 걸듯 P2P를 잇는 Rust 네트워킹 스택

1프로젝트 한줄 요약

한 문장으로 이 프로젝트가 뭘 하는지부터.

iroh = "공개키로 다이얼하는 P2P QUIC 연결 라이브러리." 보통 네트워크 프로그램은 상대의 IP 주소:포트를 알아야 연결한다. 그런데 휴대폰·노트북은 와이파이를 옮기고 NAT 뒤에 숨고 IP가 수시로 바뀐다 — 주소는 끊임없이 변한다. iroh는 발상을 뒤집는다. 변하지 않는 것, 즉 그 기기의 공개키(=신원)로 연결을 건다. "저 폰에 연결해 줘"라고 공개키만 건네면, iroh가 알아서 상대의 현재 주소를 찾고, NAT를 뚫고, 가장 빠른 경로로 암호화된 QUIC 연결을 만들어 유지한다.

정리하면 iroh의 핵심 약속은 세 가지다. ① 주소가 아니라 공개키로 연결한다(EndpointId). ② 처음엔 릴레이로 무조건 잇고, 가능해지면 홀펀칭으로 직접 연결로 갈아탄 뒤 릴레이를 뺀다. ③ 모든 연결은 QUIC + TLS로 암호화되며, 공개키가 곧 신원이라 중간자 공격이 원천 차단된다. 이 위에 파일 전송(iroh-blobs), 펍섭(iroh-gossip), 동기화 DB(iroh-docs) 같은 프로토콜을 얹어 "로컬 퍼스트(local-first)" 앱을 만든다.

2왜 주목받는가

TrendShift 일간 24위 — "공개키로 다이얼"이라는 단순한 약속과, 1.0 도달이 핵심.

분산·로컬 퍼스트 앱이 늘면서 "중앙 서버 없이 두 기기를 직접 잇는 일"의 수요가 커졌다. 하지만 NAT 통과·디스커버리·암호화·릴레이를 직접 구현하는 건 악명 높게 어렵다. iroh는 그 모든 걸 한 줄짜리 API 뒤로 숨겨 준다. 최근 주목도가 오른 이유를 다섯 가지로 본다:

① "주소가 아니라 공개키로 연결" — 발상이 단순하고 강력하다

iroh의 모든 매력은 한 문장에서 나온다. connect(EndpointId, ALPN) — 상대의 32바이트 공개키와 프로토콜 이름만 주면 끝이다. IP·포트·NAT·릴레이는 라이브러리가 알아서 처리한다. "어디에 있는가"가 아니라 "누구인가"로 연결을 거는 이 모델은, 기기가 이동해도 연결 식별자가 안 변한다는 결정적 장점을 준다.

② 자체 QUIC 엔진 noq로 갈아탔다

iroh는 오랫동안 Rust의 대표 QUIC 구현인 quinn 위에서 돌았는데, 1.0에 오며 자체 QUIC 엔진 noq(n0가 직접 개발)로 교체했다. 멀티패스(여러 경로 동시 사용)·커스텀 전송·홀펀칭 같은 iroh 특유의 요구를 QUIC 계층에서 직접 제어하려는 결정이다. 인증 암호화, 스트림 우선순위, 데이터그램 전송을 기본 제공한다.

③ Tailscale 'DERP' 계보의 릴레이 + 홀펀칭

iroh의 릴레이 프로토콜과 NAT 탐지는 Tailscale의 검증된 설계(DERP 릴레이, netcheck)에서 갈라져 나왔다(코드 주석에 출처 명시). 거기에 STUN 대신 QAD(QUIC Address Discovery)라는 최신 방식으로 자기 주소를 알아낸다. "그 회사가 수년간 프로덕션에서 검증한 NAT 통과 노하우"를 오픈소스 라이브러리로 쓸 수 있다는 점이 크다.

④ 1.0 도달 + 브라우저(WASM) + 포스트양자

이번에 v1.0.0에 도달하며 공개 API가 안정화됐다(외부 노출 타입을 cargo_check_external_types로 엄격히 관리). 게다가 wasm32 타깃을 1급으로 지원해 브라우저 안에서도 iroh 연결이 가능하고, 포스트양자 키교환 예제(pq-only-key-exchange)까지 들어 있다. "지금 쓸 수 있고, 미래도 대비했다"는 신호.

⑤ 라이브러리 + 생태계 + 무료 공용 인프라

iroh는 연결만 주고 끝이 아니다. 그 위에 얹는 iroh-blobs(BLAKE3 콘텐츠 주소 파일전송), iroh-gossip(펍섭 오버레이), iroh-docs(동기화 KV 저장소)가 함께 큰다. 게다가 n0가 전 세계 4곳에 공용 릴레이(북미 동/서·EU·아태)와 디스커버리 서버(dns.iroh.link)를 무료로 운영해, 별도 인프라 없이 바로 시작할 수 있다.

3기술 스택 전체 지도

루트 Cargo.toml workspace · 각 crate의 Cargo.toml · 실제 소스 트리에서 확인한 구성.

마음의 준비부터. iroh는 "백엔드+프론트엔드" 웹 스택이 아니라 네트워킹 라이브러리 스택이다. 전부 Rust(edition 2024, MSRV 1.91)이고, 여러 crate를 묶은 workspace(모노레포)로 되어 있다. 계층은 크게 ⓐ 핵심 라이브러리, ⓑ QUIC·암호, ⓒ 디스커버리, ⓓ NAT 통과, ⓔ 런타임·생태계로 나뉜다.

ⓐ workspace의 crate들 — 무엇이 무엇인가

ⓑ QUIC · 암호 계층 — 연결의 본체

ⓒ 디스커버리(주소 찾기) — "공개키 → 현재 주소"

ⓓ NAT 통과 · 경로 선택 — 직접 연결을 뚫는 부품

iroh의 마법 대부분이 여기 있다. net_report(iroh/src/net_report.rs)는 "내가 IPv4/IPv6로 인터넷에 닿는지, NAT 상황은 어떤지, 릴레이까지 지연은 얼마인지"를 점검한다 — Tailscale의 netcheck에서 갈라져 나왔고, 자기 공인주소 파악에 STUN 대신 QAD(QUIC Address Discovery)를 쓴다. portmapper는 공유기에 UPnP·PCP·NAT-PMP로 포트 매핑을 요청해 직접 연결 가능성을 높인다. magic socket(socket.rs)은 직접IP·릴레이·커스텀 전송을 한데 묶고 RTT가 가장 낮은 경로를 골라 보낸다(biased_rtt_path_selector).

ⓔ 런타임 · 생태계 — 주변 부품과 위에 얹는 프로토콜

비동기 런타임은 tokio다. n0가 함께 만드는 보조 crate들 — n0-future(future 유틸), n0-watcher(값 변화를 구독하는 Watcher), n0-error(스택트레이스 친화 에러), netwatch(네트워크 변화 감지) — 가 곳곳에 쓰인다. WASM 타깃에선 ws_stream_wasm·wasm-bindgen-futures 등으로 브라우저 환경을 지원한다. 그리고 응용 계층에 iroh-blobs / iroh-gossip / iroh-docs를 얹어 실제 앱을 만든다(아래 §4·§6에서 상술).

4아키텍처 심화 분석

먼저 전체 그림을 한 장으로 본 뒤, 대표 흐름 '공개키로 연결이 맺히는 과정'을 끝까지 따라간다.

iroh의 일은 "두 endpoint 사이에 가장 빠른 암호화 QUIC 경로를 만들고 유지하는 것"이다. 큰 그림은 이렇다. (1) 각 endpoint는 시작할 때 가장 가까운 릴레이를 home relay로 잡는다. (2) A가 B에 연결하려 하면 먼저 B의 home relay를 거쳐 잇는다. (3) 그 사이 양쪽은 서로의 주소를 교환하고 홀펀칭으로 직접 경로를 시도한다. (4) 직접 경로가 뚫리면 릴레이를 빼고 직접 연결만 쓴다. 부품 이름을 외우기 전에 숲부터 보자.

독수리 시점 — 전체 구조 한 장

흐름 ① — "공개키만으로 연결이 맺히기까지" (해피패스)

endpoint.connect(addr, ALPN) 한 줄 뒤에서 벌어지는 일을 순서대로 풀면:

// A가 B의 EndpointId(공개키)만 들고 connect 했을 때
1. 주소 찾기   AddressLookup(Pkarr/DNS)로 "EndpointId_b 의 RelayUrl" 조회
2. 릴레이 경유   B의 home relay 에 접속 → 암호문을 EndpointId 로 라우팅
3. 경로 탐색   net_report 가 내 NAT/주소 파악(QAD), 양쪽이 후보 주소 교환
4. 홀펀칭      양쪽이 동시에 패킷을 쏘아 NAT 에 구멍 → 직접 경로 시도
5. 승격      직접 QUIC(noq) 연결 성공 → magic socket 이 릴레이→직접 전환
6. 암호화      raw-public-key TLS 로 "정말 EndpointId_b 인지" 검증 완료

핵심 관례 하나 — 릴레이와 직접 주소를 동시에 쓸 수 있다. 처음엔 릴레이로 0초 지연 없이 잇고, 직접 경로가 준비되면 자연스럽게 갈아탄다. 사용자 코드는 이 전환을 신경 쓸 필요가 없다. 또 하나, 상대가 이미 직접 닿을 수 있으면 릴레이 없이도 연결되고, 반대로 홀펀칭이 끝내 안 되면 계속 릴레이를 통해 (느리지만) 끊김 없이 통신한다.

흐름 ② — 앱을 얹는 법: Router + ProtocolHandler + ALPN

받는 쪽은 "ALPN마다 다른 처리기"를 등록한다. Router가 들어오는 연결의 ALPN을 보고 알맞은 ProtocolHandler로 보낸다 — 한 endpoint가 여러 프로토콜을 동시에 서빙할 수 있다.

// 받는 쪽: ALPN "iroh-example/echo/0" 에 Echo 처리기 등록
let endpoint = Endpoint::bind(presets::N0).await?;
let router = Router::builder(endpoint)
    .accept(ALPN, Echo)   // ALPN → 처리기 매핑
    .spawn();

// 보내는 쪽: 같은 ALPN 으로 다이얼 후 양방향 스트림
let conn = endpoint.connect(addr, ALPN).await?;
let (mut send, mut recv) = conn.open_bi().await?;
send.write_all(b"Hello, world!").await?;
send.finish()?;                          // 이 스트림은 더 안 보냄
let echo = recv.read_to_end(1000).await?;

이 레포에서 배울 핵심 설계 패턴 둘. 첫째, magic socket(socket.rs, 108KB) — 직접IP·릴레이·커스텀을 하나의 소켓처럼 추상화하고 경로별 RTT·상태를 추적해 최적 경로로 자동 전환한다. 둘째, 릴레이는 "암호문 우체부" — 릴레이는 EndpointId만 보고 패킷을 전달할 뿐, 내용은 양쪽 키로만 풀리므로 릴레이 운영자도 트래픽을 못 읽는다. "중앙 서버를 쓰되 신뢰는 최소화"하는 모범 설계다.

5디렉토리 구조 해부

workspace 멤버 crate들과, 간판 crate iroh/src/의 내부. 큰 덩어리만 본다.

루트는 여러 crate를 묶은 workspace다. 복잡성의 대부분은 iroh/src/ 안 두 거대 파일 — endpoint.rs(158KB)와 socket.rs(108KB) — 에 모여 있다. 전자는 공개 API(Endpoint·Connection), 후자는 그 마법을 떠받치는 멀티패스 소켓이다.

6학습 포인트 (기술별)

이 레포 한 채로 배울 수 있는 네트워킹 기술과, 각각의 실습 아이디어.

iroh는 "현대 P2P 네트워킹에서 어려운 것"이 골고루 한 코드베이스에 모여 있어 공부 소재로 훌륭하다. 기술별로 무엇을 건질지 짚는다.

7하드웨어/시스템 요구사항

GPU·고사양 불필요. "Rust 툴체인"과 "약간의 네트워크 권한"이면 충분하다.

iroh는 가벼운 라이브러리다 — gossip 같은 프로토콜도 "평범한 휴대폰이 감당할 자원"으로 돈다고 README가 명시한다. 추론 모델이 아니라 네트워킹 코드라 GPU는 전혀 필요 없다. 대신 최신 Rust 툴체인과, 직접 연결을 위한 UDP 통신 권한이 중요하다.

가장 빠른 출발점은 레포를 클론해 cargo run --example echo를 돌리는 것이다. 한 프로세스 안에서 두 endpoint가 서로 echo를 주고받으므로, 외부 네트워크 설정 없이도 iroh의 연결·스트림·Router 흐름을 즉시 눈으로 확인할 수 있다.

8직접 해볼 수 있는 실습 과제

"echo 돌리기"는 5분, "직접 프로토콜·릴레이"는 한나절. 난이도 순으로.

9관련 기술 심화 학습 로드맵

iroh를 100% 소화하기 위한 6주 코스(주당 5~7시간 가정).

10핵심 키워드 사전

이 문서와 레포에 등장한 용어를 한자리에.

11참고 링크

원문·문서·관련 기술 더 파기.

• GitHub 저장소 — github.com/n0-computer/iroh (README·소스·examples)
• 공식 사이트 — iroh.computer (소개·블로그·로드맵)
• 문서 — docs.iroh.computer · API 문서 docs.rs/iroh
• TrendShift 페이지 — trendshift.io/repositories/7077
• noq (자체 QUIC 엔진) — github.com/n0-computer/noq
• Pkarr — github.com/Nuhvi/pkarr (공개키 기반 주소 레코드)
• Tailscale DERP — how NAT traversal works (릴레이·홀펀칭 배경)
• QUIC 표준 — RFC 9000 (전송 프로토콜)