Skip to content

Commit 9bf97f8

Browse files
author
shijiashuai
committed
更新README
1 parent f3574cc commit 9bf97f8

4 files changed

Lines changed: 568 additions & 267 deletions

File tree

‎.arts/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"diffEditor.renderSideBySide": false
3+
}

‎README.md‎

Lines changed: 167 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -9,21 +9,44 @@
99

1010
English | [简体中文](README.zh-CN.md) | [📖 Online Docs](https://lessup.github.io/webrtc/)
1111

12-
A minimal WebRTC demo project built with Go, providing a WebSocket signaling server and browser-based demo for peer-to-peer audio/video communication. From 1-on-1 calls to multi-party Mesh rooms, covering core WebRTC capabilities for learning and practice.
13-
14-
## Features
15-
16-
| Feature | Description |
17-
|:--------|:------------|
18-
| **WebSocket Signaling** | Gorilla WebSocket for Offer/Answer/ICE Candidate relay within rooms, with heartbeat, join acknowledgement, and explicit hangup |
19-
| **Media Controls** | Mute/unmute, camera on/off, screen sharing (`getDisplayMedia`) |
20-
| **DataChannel** | Peer-to-peer text chat without server relay |
21-
| **Local Recording** | MediaRecorder captures audio/video streams, exports `.webm` for download |
22-
| **Multi-party Mesh** | Room member list broadcast, multi-PeerConnection management, grid video layout |
23-
| **Security** | Origin validation whitelist, identity binding, duplicate ID rejection, room/client limits, auto-reconnection |
24-
| **Docker** | Multi-stage Dockerfile, Go compilation + static frontend packaging |
25-
26-
## Architecture
12+
> **A production-ready WebRTC learning platform** — From basic peer-to-peer calls to advanced multi-party Mesh architecture, this project provides a complete, well-documented implementation for understanding WebRTC fundamentals through hands-on practice.
13+
14+
**Why This Project?**
15+
- 🎯 **Learning-Oriented**: Progressive complexity from 1-on-1 to multi-party calls
16+
- 🔒 **Security-First**: Origin validation, identity binding, connection limits
17+
- 📦 **Zero-Dependency Frontend**: Pure vanilla JavaScript, no frameworks required
18+
- 🐳 **Docker-Ready**: Multi-stage builds for minimal image size
19+
- 📚 **Comprehensive Docs**: Architecture diagrams, protocol specs, and troubleshooting guides
20+
21+
## ✨ Key Features
22+
23+
### Core Capabilities
24+
| Feature | Description | Status |
25+
|:--------|:------------|:-------|
26+
| **WebSocket Signaling** | Gorilla WebSocket for Offer/Answer/ICE Candidate relay with heartbeat, join acknowledgement, and explicit hangup | ✅ Production |
27+
| **Media Controls** | Mute/unmute, camera on/off, screen sharing (`getDisplayMedia`) | ✅ Production |
28+
| **DataChannel** | Peer-to-peer text chat without server relay | ✅ Production |
29+
| **Local Recording** | MediaRecorder captures audio/video streams, exports `.webm` for download | ✅ Production |
30+
| **Multi-party Mesh** | Room member list broadcast, multi-PeerConnection management, grid video layout | ✅ Production |
31+
32+
### Security & Reliability
33+
| Feature | Description | Status |
34+
|:--------|:------------|:-------|
35+
| **Origin Validation** | Whitelist-based CORS protection for WebSocket connections | ✅ Production |
36+
| **Identity Binding** | WebSocket connections bound to single client ID and room membership | ✅ Production |
37+
| **Connection Limits** | Room/client limits, duplicate ID rejection, auto-reconnection | ✅ Production |
38+
| **Perfect Negotiation** | Collision handling and explicit hangup signaling for stable Mesh calls | ✅ Production |
39+
40+
### DevOps & Deployment
41+
| Feature | Description | Status |
42+
|:--------|:------------|:-------|
43+
| **Docker** | Multi-stage Dockerfile, Go compilation + static frontend packaging | ✅ Production |
44+
| **CI/CD** | GitHub Actions with golangci-lint, multi-version testing, Pages deployment | ✅ Production |
45+
| **Health Checks** | `/healthz` endpoint for container orchestration | ✅ Production |
46+
47+
## 🏗️ Architecture Overview
48+
49+
### System Architecture
2750

2851
```
2952
┌──────────────────────────────────────────────────────┐
@@ -48,39 +71,77 @@ A minimal WebRTC demo project built with Go, providing a WebSocket signaling ser
4871
└──────────────────────────────────────────────────────┘
4972
```
5073

51-
- **Signaling**: Browser → WebSocket `/ws` → Signal Hub (Offer/Answer/ICE relay) → Browser
52-
- **Media**: Browser ←→ WebRTC P2P audio/video / DataChannel ←→ Browser
74+
### Data Flow
75+
76+
| Flow Type | Path | Description |
77+
|:-----------|:-----|:------------|
78+
| **Signaling** | Browser → WebSocket `/ws` → Signal Hub → Browser | Offer/Answer/ICE Candidate relay |
79+
| **Media** | Browser ←→ WebRTC P2P ←→ Browser | Audio/Video streams |
80+
| **DataChannel** | Browser ←→ WebRTC P2P ←→ Browser | Text chat, file transfer |
5381

54-
## Quick Start
82+
## 🚀 Quick Start
83+
84+
### Prerequisites
85+
86+
- **Go**: 1.22 or later
87+
- **Browser**: Chrome / Edge / Firefox (latest version)
88+
- **Docker** (optional): For containerized deployment
89+
90+
### Option 1: Native Go Runtime
5591

5692
```bash
93+
# Clone the repository
5794
git clone https://github.com/LessUp/webrtc.git
5895
cd webrtc
96+
97+
# Install dependencies
5998
go mod tidy
99+
100+
# Start the server
60101
go run ./cmd/server
61-
```
62102

63-
Open two browser tabs at http://localhost:8080, enter the same room name, click a member's ID, then click **Call**.
103+
# Server will be available at http://localhost:8080
104+
```
64105

65-
### Docker
106+
### Option 2: Docker Deployment
66107

67108
```bash
109+
# Build the Docker image
68110
docker build -t webrtc .
111+
112+
# Run the container
69113
docker run --rm -p 8080:8080 webrtc
114+
115+
# Access the application at http://localhost:8080
70116
```
71117

72-
## Configuration
118+
### Testing the Application
119+
120+
1. Open two browser tabs at `http://localhost:8080`
121+
2. In both tabs, enter the same **room name** and click **Join**
122+
3. In one tab, click the other user's ID from the member list
123+
4. Click **Call** to initiate the connection
124+
5. Grant camera/microphone permissions when prompted
125+
6. You should now see the remote video stream
126+
127+
> **Note**: If testing on the same machine, you may need to disable "HTTPS-Only" mode or use incognito windows.
73128
74-
| Variable | Description | Default |
75-
|:---------|:------------|:--------|
76-
| `ADDR` | HTTP listen address | `:8080` |
77-
| `WS_ALLOWED_ORIGINS` | Comma-separated allowed origins; set to `*` for all | `localhost` |
78-
| `RTC_CONFIG_JSON` | JSON object passed to the browser as `window.__APP_CONFIG__.rtcConfig` for custom ICE/TURN config | built-in public STUN |
129+
## ⚙️ Configuration
79130

80-
Example `RTC_CONFIG_JSON`:
131+
### Environment Variables
81132

82-
```json
83-
{
133+
| Variable | Description | Default | Example |
134+
|:---------|:------------|:--------|:--------|
135+
| `ADDR` | HTTP server listen address | `:8080` | `:8080`, `0.0.0.0:8080` |
136+
| `WS_ALLOWED_ORIGINS` | Comma-separated allowed origins for WebSocket connections | `localhost` | `localhost,example.com` or `*` |
137+
| `RTC_CONFIG_JSON` | Custom ICE/TURN configuration as JSON | Built-in public STUN | See example below |
138+
139+
### Custom ICE/TURN Configuration
140+
141+
Set the `RTC_CONFIG_JSON` environment variable to configure custom STUN/TURN servers:
142+
143+
```bash
144+
export RTC_CONFIG_JSON='{
84145
"iceServers": [
85146
{ "urls": ["stun:stun.l.google.com:19302"] },
86147
{
@@ -89,71 +150,103 @@ Example `RTC_CONFIG_JSON`:
89150
"credential": "demo-password"
90151
}
91152
]
92-
}
153+
}'
93154
```
94155

95-
Health check endpoint: `GET /healthz`
156+
### Health Check
157+
158+
The server provides a health check endpoint for container orchestration:
159+
160+
```bash
161+
curl http://localhost:8080/healthz
162+
# Returns: OK
163+
```
96164

97-
## Project Structure
165+
## 📁 Project Structure
98166

99167
```
100168
webrtc/
101-
├── cmd/server/ # HTTP + WebSocket entry point
102-
│ └── main.go # Server startup, graceful shutdown, origin config
103-
├── internal/signal/ # Signaling logic
104-
│ ├── hub.go # Room management, message relay, client lifecycle
105-
│ ├── hub_test.go # Unit tests
106-
│ └── message.go # Message type definitions
107-
├── web/ # Browser frontend
108-
│ ├── index.html # UI
109-
│ ├── app.js # WebRTC & signaling logic (Mesh multi-party)
110-
│ └── styles.css # Responsive styles (light/dark theme)
111-
├── docs/ # Technical documentation
112-
│ ├── guide.md # Architecture, frontend, media, recording
113-
│ └── signaling.md # Signaling protocol deep dive
114-
├── .github/workflows/ # CI/CD
115-
│ ├── ci.yml # Go build + test + lint
116-
│ └── pages.yml # GitHub Pages deployment
117-
├── changelog/ # Change logs
118-
├── Dockerfile # Multi-stage build
119-
├── .golangci.yml # Linter configuration
120-
└── go.mod # Go module definition
169+
├── cmd/server/ # HTTP + WebSocket entry point
170+
│ └── main.go # Server startup, graceful shutdown, origin config
171+
├── internal/signal/ # Signaling logic
172+
│ ├── hub.go # Room management, message relay, client lifecycle
173+
│ ├── hub_test.go # Unit tests
174+
│ └── message.go # Message type definitions
175+
├── web/ # Browser frontend
176+
│ ├── index.html # UI
177+
│ ├── app.js # WebRTC & signaling logic (Mesh multi-party)
178+
│ └── styles.css # Responsive styles (light/dark theme)
179+
├── docs/ # Technical documentation
180+
│ ├── guide.md # Architecture, frontend, media, recording
181+
│ └── signaling.md # Signaling protocol deep dive
182+
├── .github/workflows/ # CI/CD pipelines
183+
│ ├── ci.yml # Go build + test + lint
184+
│ └── pages.yml # GitHub Pages deployment
185+
├── changelog/ # Change logs
186+
├── Dockerfile # Multi-stage build
187+
├── .golangci.yml # Linter configuration
188+
└── go.mod # Go module definition
121189
```
122190

123-
## Tech Stack
191+
## 🛠️ Tech Stack
124192

125-
| Category | Technology |
126-
|:---------|:-----------|
127-
| **Backend** | Go 1.22+, net/http, Gorilla WebSocket |
128-
| **Frontend** | HTML5 + Vanilla JavaScript + CSS3 |
129-
| **Media** | WebRTC (getUserMedia, RTCPeerConnection, DataChannel, MediaRecorder) |
130-
| **Container** | Docker (multi-stage build) |
131-
| **CI/CD** | GitHub Actions (golangci-lint + multi-version test + GitHub Pages) |
193+
| Category | Technology | Purpose |
194+
|:---------|:-----------|:--------|
195+
| **Backend** | Go 1.22+, net/http, Gorilla WebSocket | Signaling server, WebSocket handling |
196+
| **Frontend** | HTML5 + Vanilla JavaScript + CSS3 | Zero-dependency browser UI |
197+
| **Media** | WebRTC APIs | getUserMedia, RTCPeerConnection, DataChannel, MediaRecorder |
198+
| **Container** | Docker (multi-stage) | Minimal image size, easy deployment |
199+
| **CI/CD** | GitHub Actions | golangci-lint, multi-version testing, Pages deployment |
132200

133-
## Documentation
201+
## 📚 Documentation
134202

135-
- [Technical Guide](docs/guide.md) — Architecture, frontend, media, recording
136-
- [Signaling Deep Dive](docs/signaling.md) — Signaling & room management details
137-
- [Roadmap](ROADMAP.md) — Development plan & progress tracking
138-
- [Contributing](CONTRIBUTING.md) — Development workflow & code standards
203+
| Document | Description |
204+
|:---------|:------------|
205+
| [Technical Guide](docs/guide.md) | Architecture, frontend implementation, media controls, recording |
206+
| [Signaling Deep Dive](docs/signaling.md) | Signaling protocol, room management, message flow |
207+
| [Roadmap](ROADMAP.md) | Development plan, progress tracking, future features |
208+
| [Contributing](CONTRIBUTING.md) | Development workflow, code standards, PR guidelines |
139209

140-
## Current Guardrails
210+
## 🔒 Security Features
141211

142-
- The signaling server now binds each WebSocket connection to a single client ID and room membership, instead of trusting later messages blindly.
143-
- Duplicate client IDs in the same room are rejected instead of replacing an existing connection.
144-
- WebSocket connections use read limits, deadlines, pong handling, and server-driven ping frames.
145-
- The browser uses perfect-negotiation style collision handling and explicit `hangup` signaling for more stable multi-peer Mesh calls.
212+
This project implements several security best practices:
146213

147-
## Roadmap
214+
- **Identity Binding**: Each WebSocket connection is bound to a single client ID and room membership
215+
- **Duplicate Rejection**: Duplicate client IDs in the same room are rejected
216+
- **Connection Limits**: Room and client limits prevent resource exhaustion
217+
- **Origin Validation**: Whitelist-based CORS protection for WebSocket connections
218+
- **Perfect Negotiation**: Collision handling and explicit hangup signaling for stable Mesh calls
219+
- **WebSocket Hardening**: Read limits, deadlines, pong handling, server-driven ping frames
148220

221+
## 🗺️ Roadmap
222+
223+
### Completed ✅
149224
- [x] 1-on-1 call with status display, error handling, heartbeat
150225
- [x] Mute/camera/screen sharing, DataChannel chat, local recording
151226
- [x] Room member list, auto-call prompt, multi-party Mesh
152227
- [x] Docker multi-stage build & deployment
228+
229+
### In Progress 🚧
153230
- [ ] TURN support (coturn)
154231
- [ ] HTTPS/WSS reverse proxy
232+
233+
### Future 🔮
155234
- [ ] Multi-party calls via SFU
235+
- [ ] End-to-end encryption
236+
- [ ] Mobile app support
237+
238+
## 🤝 Contributing
239+
240+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
241+
- Development workflow
242+
- Code standards
243+
- Commit message format
244+
- Pull request process
245+
246+
## 📄 License
247+
248+
This project is licensed under the [MIT License](LICENSE).
156249

157-
## License
250+
---
158251

159-
[MIT](LICENSE)
252+
**Made with ❤️ by the LessUp Team**

0 commit comments

Comments
 (0)