이 프로젝트는 별도의 서버 없이 WebRTC를 사용하여 VS Code 인스턴스 간에 실시간으로 코드를 공유하고 편집할 수 있는 P2P 기반 협업 도구입니다.
🚀 주요 기능
간편한 자동 연결 (PeerJS): 방 이름만으로 복잡한 SDP 복사 없이 즉시 P2P 연결이 가능합니다. (PeerJS 무료 시그널링 서버 활용)
서버리스 P2P 직접 통신: 실제 데이터 교환은 WebRTC(SimplePeer)를 사용하여 중앙 서버를 거치지 않고 직접 통신합니다.
실시간 코드 및 커서 동기화: 문서 변경 사항 및 다수 참가자의 커서 위치/선택 영역을 실시간으로 시각화합니다.
파일 공유 및 자동 동기화: 호스트가 공유한 파일을 게스트가 즉시 열람할 수 있으며, 중간에 입장한 게스트도 현재 공유 중인 모든 파일을 자동으로 전달받습니다.
사용자 관리: 각 참가자별 고유 색상 할당, 이름 변경 기능을 제공합니다.
📂 디렉터리 구조
src/
├── core/ # P2P 동기화 엔진 및 피어 관리 로직
│ ├── HubManager.ts # Webview(엔진)와의 통신 인터페이스 및 시그널링 조율
│ └── SyncEngine.ts # 실시간 편집, 상태 동기화 및 파일 I/O 핵심 엔진
├── ui/ # UI 및 뷰 프로바이더
│ ├── SidebarProvider.ts
│ └── templates.ts # 사이드바 UI 및 Webview 엔진(PeerJS/SimplePeer) 로직
├── types/ # 타입 및 인터페이스 정의
└── utils/ # 경로 정리 등 유틸리티 함수
🛠 핵심 기술: 실시간 동기화 아키텍처
1. 하이브리드 시그널링 (PeerJS + SimplePeer)
자동 시그널링: PeerJS를 활용하여 방 이름을 ASCII 안전 코드로 인코딩 후 시그널링 서버에 등록합니다. 이를 통해 사용자 간의 초기 WebRTC 핸드셰이크(SDP 교환)를 자동화합니다.
수동 모드 유지: 보안 정책상 외부 시그널링 서버 접속이 불가능한 환경을 위해 기존의 직접 SDP 복사/붙여넣기 방식도 병행 지원합니다.
독립적 데이터 통로: 연결이 확립된 후에는 SimplePeer를 통한 순수 P2P 채널로만 데이터를 전송하여 성능과 보안을 확보합니다.
2. 향상된 사용자 경험 (UX)
상태 가시성: 연결 중 "서버 연결 중", "참여 중" 등의 로딩 상태를 시각화하고 버튼 비활성화를 통해 오작동을 방지합니다.
에러 핸들링: 방 이름 중복이나 서버 연결 실패 시 사용자에게 알림을 제공하고 자동으로 수동 모드 대안을 제시합니다.
지능형 동기화: 새로운 게스트가 입장하면 호스트가 현재 세션에서 공유 중인 모든 파일의 최신 스냅샷을 해당 게스트에게만 타겟팅하여 즉시 전송합니다.
2. VS Code WebView 엔진 및 메신저 패턴
WebView 기반 Engine: 에디터 내에서 실행되는 Webview를 독립적인 P2P 엔진으로 사용합니다. 이는 에디터의 메인 프로세스와 통신을 분리하여 성능 영향을 최소화합니다.
메시지 라우팅 (HubManager): 메인 스레드(Extension Host)와 Webview(Engine) 사이의 통신 브릿지 역할을 수행합니다. targetPeerId를 활용하여 브로드캐스트가 아닌 특정 피어를 대상으로 하는 라우팅을 지원합니다.
3. 실시간 코드 동기화 (SyncEngine)
스냅샷 및 해시 기반 복구: SYNC_FULL을 통한 전체 동기화 방식에, 1초마다 파일의 MD5 해시를 교환하는 **파일 무결성 검사(Integrity Check)**를 도입했습니다. 이를 통해 일시적인 네트워크 불일치를 실시간으로 감지하고 자동으로 전체 동기화를 요청하여 데이터의 정합성을 완벽하게 보장합니다.
적응형 디바운싱 (Adaptive Debouncing): 타이핑 속도에 따라 동기화 메시지 전송 간격을 동적으로 조절합니다. 빠른 타이핑 시에는 50ms로 반응성을 극대화하고, 느린 타이핑 시에는 200ms로 조절하여 네트워크 트래픽을 최적화합니다. 이는 실시간 편집 시 발생할 수 있는 데이터 증식 루프를 원천 차단합니다.
보안 전송 (Participant-only Broadcast): 호스트는 현재 방에 승인되어 participants 목록에 포함된 피어에게만 데이터를 전송합니다. 대기 중인 피어는 파일 내용 및 커서 정보를 수신할 수 없도록 격리되어 있습니다.
루프 방지 알고리즘: onDidChangeTextDocument를 통한 로컬 입력 감지와 WorkspaceEdit를 통한 원격 동기화가 무한 루프를 형성하지 않도록 isApplyingRemoteChange 플래그와 contentChanges를 이용한 2단계 가드 시스템을 운영합니다.
데코레이션 기반 커서 렌더링: createTextEditorDecorationType을 사용하여 각 게스트의 커서와 선택 영역을 실시간으로 시각화합니다. 실시간 전송된 cursorPos와 selectionRange를 기반으로, 메시지에 포함된 고유 userId를 통해 각 사용자의 색상을 구분하여 매 프레임 업데이트합니다.
4. 독립적인 세션 및 파일 관리
Dynamic Storage: 각 게스트는 고유한 peerId를 할당받는 즉시, globalStorageUri 하위에 고유 폴더(방이름/peerId/)를 생성하여 인스턴스 간 파일 충돌을 방지합니다.
참고 (Yjs 사용): 현재 프로젝트 의존성에는 Yjs 및 y-protocols가 포함되어 있으나, 현재 구현된 동기화 엔진은 커스텀 스냅샷/이벤트 기반 동기화 로직을 따르고 있습니다. 향후 대규모 병합 및 충돌 해결을 위해 Yjs로의 전환을 고려할 수 있습니다.
⚠️ 네트워크 연결 문제 해결 (Troubleshooting)
이 프로젝트는 별도의 서버를 거치지 않는 P2P(Peer-to-Peer) 통신 방식을 사용하므로, 네트워크 환경에 따라 연결 제한이 있을 수 있습니다.
1. 연결 가능 환경
유선 LAN (동일 라우터/서브넷): 유선 네트워크는 기기 간 직접 통신을 기본적으로 허용하므로 가장 안정적으로 연결됩니다.
Wi-Fi: 공유기 정책에 따라 연결이 차단될 수 있습니다. (아래 "주의사항" 참조)
2. 연결이 되지 않는 경우
서로 다른 네트워크/와이파이: 다른 공유기에 연결된 기기 간에는 NAT/방화벽 문제로 인해 직접적인 P2P 연결이 불가능합니다. 이는 WebRTC의 설계상 네트워크가 물리적으로 격리되어 있기 때문입니다.
Wi-Fi 환경에서의 통신 차단: 동일 와이파이임에도 연결되지 않는다면, 공유기의 'AP Isolation' 또는 '내부 기기 간 통신 금지' 옵션이 켜져 있을 가능성이 높습니다.
해결책: 공유기 설정 페이지에서 'AP Isolation' 또는 'Client Isolation' 옵션을 비활성화(Disable)하거나, 네트워크 프로필을 '공용'에서 '개인'으로 변경하여 확인해 보세요.
TURN 서버 미지원: 현재 프로젝트는 직접 통신(STUN/Host) 기반으로 설계되어 있습니다. 인터넷 환경 등 NAT가 엄격한 곳에서 연결하려면 별도의 TURN(중계) 서버 설정이 필요합니다.
3. 결론
동일한 유선/무선 네트워크 환경에서만 작동하는 프로젝트로 설계되었음을 참고해 주시기 바랍니다. 다른 네트워크 간의 통신이 꼭 필요할 경우 향후 로드맵에 따라 TURN 서버 도입을 고려할 예정입니다.
⚙️ 설정 방법
프로젝트 루트에서 의존성을 설치합니다:
npm install
개발 모드(코드 변경 시 자동 빌드):
npm run watch
프로덕션 빌드(최종 컴파일):
npm run compile
VS Code에서 F5를 눌러 Extension Development Host 창을 실행합니다.
호스트 창에서 "Create Sharing Room"을 선택하고, 게스트 창에서 "Join Sharing Room"을 선택하여 연결을 진행합니다.
📅 향후 로드맵 (Roadmap)
1단계: 세션 보안 및 관리 (Security & Management) (5월 26일 완료)
승인 기반 참여: 게스트가 소개(Description)와 함께 참여 요청을 보내면, 호스트가 승인해야만 접속이 가능하도록 개선.
강제 퇴장 (Kick): 호스트가 특정 참가자를 세션에서 즉시 퇴장시킬 수 있는 기능.
2단계: 정밀한 권한 제어 (Granular Permissions) (6월 01일 완료)
사용자별 수정 권한: 참가자별로 읽기 전용/편집 가능 권한을 개별적으로 설정.
파일 담당자 지정: 특정 파일에 대해 지정된 사용자만 편집할 수 있도록 제한.
편집 가능 구간 보호: 파일 내에서 호스트가 지정한 특정 라인 구간만 편집할 수 있도록 제한하는 기능.
3단계: 협업 도구 고도화 (Advanced Collaboration)
사이드바 채팅: 별도 메신저 없이 VS Code 내에서 직접 소통 가능한 채팅 기능.
호스트 팔로우 모드 (Follow Me): 호스트의 파일 전환 및 스크롤을 게스트들이 실시간으로 추적하는 기능.
공유 터미널 (Read-only): 호스트의 터미널 실행 결과를 게스트들이 실시간으로 모니터링.
변경 이력 하이라이트: 누가 어떤 코드를 수정했는지 시각적으로 표시.
4단계: 지능형 검토 및 병합 (Intelligent Review & Merge)
Diff 뷰어 통합: 호스트가 파일 공유를 중지할 때, 원본 파일과 최종 협업 스냅샷을 VS Code의 내장 Diff 뷰어로 열어 변경 사항을 시각적으로 대조.
선택적 병합 (Selective Merge): 모든 변경 사항을 한 번에 덮어쓰는 대신, 호스트가 검토 후 필요한 변경 부분만 원본 파일에 반영할 수 있는 워크플로우 제공.
