bdpeer

README

bdpeer

같은 네트워크 또는 인터넷을 통해 피어를 자동으로 발견하고 텍스트 메시지와 파일을 주고받는 크로스 플랫폼 P2P TUI 앱.

┌──────────────────────────────────────────────────────┐
│  bdpeer  [alice]                                     │
├──────────────┬───────────────────────────────────────┤
│ Peers        │ Chat: bob                             │
│              │                                       │
│ ▶ bob        │ bob: 안녕!                            │
│   carol      │ you: 파일 보낼게                      │
│              │                                       │
│              │ > /file ~/photo.jpg█                  │
│ ↑/↓ select  │ Enter send  /file <path>  Esc quit   │
└──────────────┴───────────────────────────────────────┘

특징

• 자동 피어 발견 — 같은 Wi-Fi(mDNS/Bonjour) 또는 다른 네트워크(libp2p DHT)에서 설정 없이 탐색
• 닉네임 연결 — /connect <닉네임> 으로 DHT에서 상대방을 검색해 연결
• 수동 연결 — /connect <multiaddr> 로 주소를 직접 입력해 연결
• 텍스트 채팅 — 선택한 피어에게 실시간 메시지 전송
• 파일 전송 — /file <경로> 명령으로 파일 전송, SHA-256 체크섬 검증
• 안정적인 identity — peer ID가 앱 재시작 후에도 유지됨
• 자체 업데이트 — bdpeer --update 한 줄로 최신 버전으로 교체
• 크로스 플랫폼 — macOS, Windows, Linux 지원

설치

Releases 페이지에서 플랫폼에 맞는 바이너리를 다운로드합니다.

macOS

# 압축 해제
tar -xzf bdpeer_*_darwin_*.tar.gz

# Gatekeeper 차단 해제 (Developer ID 미서명)
xattr -d com.apple.quarantine bdpeer

# 실행
./bdpeer

시스템 환경설정 → 개인 정보 보호 및 보안에서 "어쨌든 허용"을 눌러도 됩니다. 최초 실행 시 Bluetooth 권한 요청 다이얼로그가 표시됩니다 — 근거리 피어 발견(BLE)에 사용되며 허용해야 BLE 경로가 동작합니다.

Linux

tar -xzf bdpeer_*_linux_*.tar.gz
chmod +x bdpeer
./bdpeer

Windows

zip 압축 해제 후 bdpeer.exe 실행.

직접 빌드

# 현재 플랫폼 빌드
make build

# 실행
./dist/bdpeer

사용법

./bdpeer              # TUI 실행
./bdpeer --help       # 도움말
./bdpeer --version    # 버전 확인
./bdpeer --update     # 최신 버전으로 업데이트

첫 실행 시 닉네임을 입력하면 메인 화면으로 전환됩니다. 같은 네트워크의 피어는 즉시 발견되고, 다른 서브넷·인터넷 너머 피어는 DHT를 통해 약 10–30초 후 자동으로 나타납니다.

Tab 키로 우측 패널을 로그 뷰로 전환하면 피어 발견 과정(DHT 광고·검색·연결 시도)을 실시간으로 확인할 수 있습니다.

키 / 명령	동작
← / →	패널 이동 (피어 / 채팅 / 파일) — 활성 패널은 보더가 강조됨
↑ / ↓	패널 내 항목 선택 (피어 / 파일 / 메시지 스크롤)
Enter	메시지 전송 · 디렉토리 진입 · 파일 전송 확인
Tab	채팅 ↔ 로그 패널 전환
1 / 2 / 3	피어 / 채팅 / 파일 패널로 바로 이동
/connect <닉네임>	닉네임으로 피어 검색 후 연결 (DHT)
/connect <multiaddr>	주소로 피어 직접 연결
/file <경로>	파일 전송
Ctrl+C / Esc / q	종료

파일 패널에서는 긴 파일명은 자동 절단되고 ↑ 12/45 ↓ 형태의 스크롤 인디케이터가 표시됩니다. 파일 전송 시 채팅 패널 하단에 시각적 진행률 바([████████░░░░] 67%)가 송·수신 양쪽에 표시됩니다. v0.5.3부터 송신측은 모든 바이트를 송출한 뒤 수신측의 FILE_ACK가 도착할 때까지 송출 완료 · 수신 대기 중... 상태로 표시되어, transport 버퍼만 비운 상태와 실제 전송 완료를 구분합니다.

다른 서브넷 피어와 연결하기

상단 타이틀에 표시된 내 주소를 상대방에게 전달하면 수동 연결이 가능합니다.

 bdpeer  [alice]  /ip4/192.168.50.71/tcp/12345/p2p/12D3KooW...

상대방 입력창에서:

/connect /ip4/192.168.50.71/tcp/12345/p2p/12D3KooW...

빌드

make build          # 현재 플랫폼 (BLE 포함)
make build-mac      # macOS arm64 + amd64 (CGO=1, BLE 포함)
make build-win      # Windows amd64 (BLE 스캔 포함)
make build-linux    # Linux amd64 (BLE 스캔 포함)

피어 발견 프로토콜

프로토콜	지원 환경	설명
mDNS/Bonjour (_bdpeer._tcp)	macOS, iOS, Android, Windows 10+	로컬 Wi-Fi 자동 발견
SSDP/UPnP	Windows, Android	Windows 네트워크 탐색
WS-Discovery	Windows	탐색기 → 네트워크 폴더 표시
BLE + WebRTC	macOS (기본 내장, CoreBluetooth)	BLE로 발견 → WebRTC로 연결 — 다른 서브넷·NAT 무관 (실패 시 BLE 직접 전송)
BLE GATT	Linux (기본 내장, tinygo)	BLE 발견 + GATT DataChar로 직접 메시지 송수신
BLE 스캔	Windows (기본 내장, tinygo)	근거리 근접 발견
libp2p DHT	인터넷	서브넷이 달라도 자동 발견 (시작 후 ~10초)

SSDP 자동 연결 (v0.4.3+): SSDP 광고에 libp2p peer.ID가 포함되어, 같은 LAN의 Windows/Android 피어가 발견되면 별도 /connect 없이도 libp2p로 자동 연결됩니다. 발견 즉시 양방향 텍스트·파일 전송 가능.
BLE→WebRTC: macOS 기본 바이너리에 포함(별도 빌드 불필요). BLE로 상대를 발견하면 WebRTC SDP offer/answer를 BLE로 교환하고 STUN/TURN으로 NAT를 뚫어 직접 연결합니다. 알파벳 순으로 낮은 닉네임이 Initiator(offer), 높은 닉네임이 Responder(answer)로 자동 결정됩니다. v0.3.5부터 ICE gathering 타임아웃 시 연결을 끊지 않고 수집된 candidate로 핸드셰이크를 계속 진행하여 기업망 등 STUN/TURN 응답이 느린 환경에서도 연결 성공률이 향상됩니다. v0.4.3부터 BLE 발견 즉시 사이드바에 잠정 항목으로 표시되어 WebRTC 핸드셰이크 진행 상황을 바로 확인할 수 있습니다.
BLE 데이터 전송 (v0.4+): BLE GATT DataChar(BD9E0004)로 텍스트 프레임을 직접 송수신합니다. macOS↔macOS는 WebRTC 업그레이드 전·도중에도 BLE 폴백으로 즉시 통신이 가능하며 WebRTC가 성공하면 자동으로 전환됩니다. macOS↔Linux는 BLE GATT만으로 통신합니다. 단, BLE 대역폭(~10KB/s) 한계로 파일 전송은 지원하지 않습니다. v0.5.2부터 BLE 연결이 중간에 끊어져도 재조립 버퍼가 자동으로 초기화되어 다음 메시지가 오염되지 않습니다(이전 버전에서 invalid character '\x00' 에러로 나타나던 frame desync 해결).
TURN 릴레이: STUN만으로 NAT 홀펀칭이 실패하면(기업망 등) Open Relay Project TURN 서버가 자동으로 중계합니다. 전송 데이터는 DTLS로 암호화되어 TURN 서버도 내용을 볼 수 없습니다. 자체 TURN 서버를 사용하려면 아래 설정을 참고하세요.
AirDrop: Apple 전용 AWDL 프로토콜 — 구현 불가. 같은 Wi-Fi에서는 Bonjour로 발견 가능.
Quick Share: Google Nearby Connections 와이어 프로토콜 필요 (Phase 3 예정).
DHT: 공개 IPFS DHT(bdpeer/v1 네임스페이스) 사용. NAT 홀펀칭(DCUtR) + AutoRelay 지원.

TURN 서버 설정 (선택)

BLE→WebRTC는 STUN 실패 시 Open Relay Project TURN 서버를 자동으로 사용합니다. 자체 TURN 서버(coturn 등)를 사용하려면 config 파일에 추가하세요.

config 파일 경로

플랫폼	경로
macOS	~/Library/Application Support/bdpeer/config.json
Linux	~/.config/bdpeer/config.json
Windows	%APPDATA%\bdpeer\config.json

{
  "nickname": "alice",
  "turn_servers": [
    {
      "url": "turn:my-coturn.example.com:3478",
      "username": "user",
      "credential": "password"
    }
  ]
}

turn_servers를 설정하면 Open Relay 대신 지정한 서버만 사용합니다.

기술 스택

• Go 1.22+
• libp2p — P2P 네트워킹
• Bubble Tea — TUI 프레임워크
• zeroconf — mDNS/Bonjour
• go-ssdp — SSDP/UPnP
• tinygo bluetooth — BLE 스캔 + GATT central (Linux DataChar 송수신, Windows)
• CoreBluetooth — BLE peripheral+central+WebRTC 시그널링+DataChar 데이터 전송, macOS
• pion/webrtc — WebRTC STUN/TURN NAT traversal (v4)

라이선스

MIT