file-transfer-go

Chuan is a WebRTC-based P2P file transfer application. The architecture is split into three distinct planes to ensure privacy and performance:

1. Control Plane (HTTP): Uses REST APIs to create and query rooms.
2. Signaling Plane (WebSocket): Uses WebSockets to exchange SDP (offer/answer) and ICE candidates between peers. The server acts as a pure relay and does not parse these messages.
3. Data Plane (P2P): Actual files, text, and media streams are transferred directly between browsers via WebRTC DataChannel and MediaStream, bypassing the server entirely.

Key Technical Specs:

• File Transfer: Uses WebRTC DataChannel with 256KB chunks, CRC32 checksums, and ACK confirmations.
• Text Messaging: Real-time bidirectional sync via DataChannel.
• Desktop Sharing: Uses MediaStream via getDisplayMedia.

The Chuan system uses four distinct communication planes to handle different responsibilities:

1. Control Plane (HTTP REST): Used for room management and status queries (Browser ↔ Server).
2. Signaling Plane (WebSocket): Used for SDP/ICE exchange and connection management (Browser ↔ Server via relay).
3. Data Plane (DataChannel): Used for P2P file and text transfers (Browser ↔ Browser).
4. Media Plane (MediaStream): Used for P2P desktop sharing and video streams (Browser ↔ Browser).

To reduce bandwidth consumption from O(textLength) to O(editSize) during text transfers, send only the differences (diffs) rather than the full text content on every keystroke.

// Example message format for text-diff
{
  "type": "text-diff",
  "channel": "text-transfer",
  "payload": {
    "offset": 5,
    "deleteCount": 0,
    "insertText": "a",
    "version": 42
  }
}

To develop locally, clone the repository, start the Go backend using make dev, and then set up the Next.js frontend in the chuan-next directory.

1. Clone the repository.
2. Run make dev in the root directory to start the backend.
3. Navigate to chuan-next, install dependencies, and start the development server.

# 克隆项目
git clone https://github.com/MatrixSeven/file-transfer-go.git
cd file-transfer-go

# 启动后端服务
make dev

# 启动前端服务
cd chuan-next
npm install
npm run dev

The frontend uses URL parameters to control the application mode and feature set. Use the following mapping:

type parameter (Selects the Tab):

• webrtc: File Transfer
• message: Text/Image Transfer
• desktop: Desktop Sharing
• wechat: WeChat Group QR
• settings: WebRTC Settings

mode parameter (Selects Sub-mode):

• send: Sender mode
• receive: Receiver mode

code parameter (Room Access):

• code=ABC123: Automatically enters the room with the 6-digit code ABC123.

Example URLs:

• /?type=webrtc&mode=send — File Transfer (Sender)
• /?type=webrtc&mode=receive&code=ABC123 — File Transfer (Receiver, auto-joined)

The easiest way to deploy the entire stack (frontend and backend) is using Docker Compose. This will start all necessary services in detached mode.

After running the command, the application is accessible at http://localhost:8080.

# 一键启动所有服务
docker-compose up -d

# 访问应用
open http://localhost:8080

In development mode, Next.js acts as a proxy layer that forwards requests to the Go backend. The following routes are proxied:

In production, the frontend and Go backend should be deployed on the same origin to avoid the need for proxying.

To run the project locally for development, you need to run both the Go backend and the Next.js frontend in separate terminal sessions.

1. Backend: Run the Go server on port :8080.
2. Frontend: Run the Next.js application on port :3000 using turbopack.

Note the API call chain: Browser → localhost:3000/api/* → Next.js API Route → localhost:8080/api/*.

To improve throughput from serial chunk-by-chunk waiting (which is limited by RTT) to a high-performance model, implement a sliding window mechanism similar to TCP. This allows multiple chunks to be in-flight simultaneously.

Implementation Requirements:

• Maintain a windowSize (e.g., starting at 4, dynamically adjusted based on packet loss).
• Each in-flight chunk must have an independent timeout.
• Ensure the receiver can correctly associate concurrent chunks.

To build and run the full stack locally without Docker, use the provided build script and run the resulting binary.

git clone https://github.com/MatrixSeven/file-transfer-go.git
cd file-transfer-go
./build-fullstack.sh 
./dist/file-transfer-go