xtr.dev/rondevu-server
1
0
Fork 0
mirror of https://github.com/xtr-dev/rondevu-server.git synced 2025-12-13 20:33:25 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update README to document current v0.4 API

Browse Source 
- Remove outdated UUID-based endpoint documentation
- Document actual service:version@username FQN format
- Add /offers/poll combined polling endpoint
- Update all endpoint paths to match actual implementation
- Document ICE candidate role filtering
- Add migration notes from v0.3.x
This commit is contained in:
Bas van den Aakster
2025-12-10 21:03:51 +01:00
parent 1bf21d7df8
commit 95596dd462
1 changed files with 224 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

335
README.md
View File

@@ -2,9 +2,9 @@
[![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-server)](https://www.npmjs.com/package/@xtr-dev/rondevu-server) [![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-server)](https://www.npmjs.com/package/@xtr-dev/rondevu-server)
🌐 **DNS-like WebRTC signaling with username claiming and service discovery** 🌐 **Simple WebRTC signaling with username-based discovery**
Scalable WebRTC signaling server with cryptographic username claiming, service publishing, and privacy-preserving discovery. Scalable WebRTC signaling server with cryptographic username claiming, service publishing with semantic versioning, and efficient offer/answer exchange.
**Related repositories:** **Related repositories:**
- [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client)) - [@xtr-dev/rondevu-client](https://github.com/xtr-dev/rondevu-client) - TypeScript client library ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-client))
@@ -16,11 +16,12 @@ Scalable WebRTC signaling server with cryptographic username claiming, service p
## Features ## Features
- **Username Claiming**: Cryptographic username ownership with Ed25519 signatures (365-day validity, auto-renewed on use) - **Username Claiming**: Cryptographic username ownership with Ed25519 signatures (365-day validity, auto-renewed on use)
- **Service Publishing**: Package-style naming with semantic versioning (com.example.chat@1.0.0) - **Service Publishing**: Service:version@username naming (e.g., `chat:1.0.0@alice`)
- **Privacy-Preserving Discovery**: UUID-based service index prevents enumeration - **Service Discovery**: Random and paginated discovery for finding services without knowing usernames
- **Public/Private Services**: Control service visibility - **Semantic Versioning**: Compatible version matching (chat:1.0.0 matches any 1.x.x)
- **Stateless Authentication**: AES-256-GCM encrypted credentials, no server-side sessions - **Stateless Authentication**: AES-256-GCM encrypted credentials, no server-side sessions
- **Complete WebRTC Signaling**: Offer/answer exchange and ICE candidate relay - **Complete WebRTC Signaling**: Offer/answer exchange and ICE candidate relay
- **Efficient Batch Polling**: Combined endpoint for answers and ICE candidates (50% fewer HTTP requests)
- **Dual Storage**: SQLite (Node.js/Docker) and Cloudflare D1 (Workers) backends - **Dual Storage**: SQLite (Node.js/Docker) and Cloudflare D1 (Workers) backends
## Architecture ## Architecture
@@ -30,11 +31,13 @@ Username Claiming → Service Publishing → Service Discovery → WebRTC Connec
alice claims "alice" with Ed25519 signature alice claims "alice" with Ed25519 signature
↓ ↓
alice publishes com.example.chat@1.0.0 with multiple offers → receives UUID abc123 alice publishes chat:1.0.0@alice with offers
↓ ↓
bob requests alice/com.example.chat@1.0.0 → gets compatible service with available offer bob queries chat:1.0.0@alice (direct) or chat:1.0.0 (discovery) → gets offer SDP
↓ ↓
WebRTC connection established via offer/answer exchange bob posts answer SDP → WebRTC connection established
↓
ICE candidates exchanged via server relay
``` ```
## Quick Start ## Quick Start
@@ -61,9 +64,27 @@ npx wrangler deploy
#### `GET /` #### `GET /`
Returns server version and info Returns server version and info
**Response:**
```json
{
"version": "0.4.0",
"name": "Rondevu",
"description": "DNS-like WebRTC signaling with username claiming and service discovery"
}
```
#### `GET /health` #### `GET /health`
Health check endpoint with version Health check endpoint with version
**Response:**
```json
{
"status": "ok",
"timestamp": 1733404800000,
"version": "0.4.0"
}
```
#### `POST /register` #### `POST /register`
Register a new peer and receive credentials (peerId + secret) Register a new peer and receive credentials (peerId + secret)
@@ -77,19 +98,27 @@ Generates a cryptographically random 128-bit peer ID.
} }
``` ```
### User Management (RESTful) ### User Management
#### `GET /users/:username` #### `GET /users/:username`
Check username availability and claim status Check username availability and claim status
**Response:** **Response (Available):**
```json
{
"username": "alice",
"available": true
}
```
**Response (Claimed):**
```json ```json
{ {
"username": "alice", "username": "alice",
"available": false, "available": false,
"claimedAt": 1733404800000, "claimedAt": 1733404800000,
"expiresAt": 1765027200000, "expiresAt": 1765027200000,
"publicKey": "..." "publicKey": "base64-encoded-ed25519-public-key"
} }
``` ```
@@ -108,9 +137,8 @@ Claim a username with cryptographic proof
**Response:** **Response:**
```json ```json
{ {
"username": "alice", "success": true,
"claimedAt": 1733404800000, "username": "alice"
"expiresAt": 1765027200000
} }
``` ```
@@ -120,37 +148,10 @@ Claim a username with cryptographic proof
- Timestamp must be within 5 minutes (replay protection) - Timestamp must be within 5 minutes (replay protection)
- Expires after 365 days, auto-renewed on use - Expires after 365 days, auto-renewed on use
#### `GET /users/:username/services/:fqn` ### Service Management
Get service by username and FQN with semver-compatible matching
**Semver Matching:** #### `POST /services`
- Requesting `chat@1.0.0` matches any `1.x.x` version Publish a service with offers (requires authentication and username signature)
- Major version must match exactly (`chat@1.0.0` will NOT match `chat@2.0.0`)
- For major version 0, minor must also match (`0.1.0` will NOT match `0.2.0`)
- Returns the most recently published compatible version
**Response:**
```json
{
"uuid": "abc123",
"serviceId": "service-id",
"username": "alice",
"serviceFqn": "chat.app@1.0.0",
"offerId": "offer-hash",
"sdp": "v=0...",
"isPublic": true,
"metadata": {},
"createdAt": 1733404800000,
"expiresAt": 1733405100000
}
```
**Note:** Returns a single available offer from the service. If all offers are in use, returns 503.
### Service Management (RESTful)
#### `POST /users/:username/services`
Publish a service with multiple offers (requires authentication and username signature)
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
@@ -158,92 +159,125 @@ Publish a service with multiple offers (requires authentication and username sig
**Request:** **Request:**
```json ```json
{ {
"serviceFqn": "com.example.chat@1.0.0", "serviceFqn": "chat:1.0.0@alice",
"offers": [ "offers": [
{ "sdp": "v=0..." }, { "sdp": "v=0..." },
{ "sdp": "v=0..." } { "sdp": "v=0..." }
], ],
"ttl": 300000, "ttl": 300000,
"isPublic": false,
"metadata": { "description": "Chat service" },
"signature": "base64-encoded-signature", "signature": "base64-encoded-signature",
"message": "publish:alice:com.example.chat@1.0.0:1733404800000" "message": "publish:alice:chat:1.0.0@alice:1733404800000"
} }
``` ```
**Response (Full service details):** **Response:**
```json ```json
{ {
"uuid": "uuid-v4-for-index",
"serviceId": "uuid-v4", "serviceId": "uuid-v4",
"username": "alice", "username": "alice",
"serviceFqn": "com.example.chat@1.0.0", "serviceFqn": "chat:1.0.0@alice",
"offers": [ "offers": [
{ {
"offerId": "offer-hash-1", "offerId": "offer-hash-1",
"sdp": "v=0...", "sdp": "v=0...",
"createdAt": 1733404800000, "createdAt": 1733404800000,
"expiresAt": 1733405100000 "expiresAt": 1733405100000
},
{
"offerId": "offer-hash-2",
"sdp": "v=0...",
"createdAt": 1733404800000,
"expiresAt": 1733405100000
} }
], ],
"isPublic": false,
"metadata": { "description": "Chat service" },
"createdAt": 1733404800000, "createdAt": 1733404800000,
"expiresAt": 1733405100000 "expiresAt": 1733405100000
} }
``` ```
**Service FQN Format:** **Service FQN Format:**
- Service name: Reverse domain notation (e.g., `com.example.chat`) - Format: `service:version@username`
- Version: Semantic versioning (e.g., `1.0.0`, `2.1.3-beta`) - Service name: Lowercase alphanumeric + dash (e.g., `chat`, `video-call`)
- Complete FQN: `service-name@version` (e.g., `com.example.chat@1.0.0`) - Version: Semantic versioning (e.g., `1.0.0`, `2.1.3`)
- Username: Claimed username
- Example: `chat:1.0.0@alice`
**Validation:** **Validation:**
- Service name pattern: `^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$` - Service name pattern: `^[a-z0-9][a-z0-9-]*[a-z0-9]$`
- Length: 3-128 characters - Version pattern: `^[0-9]+\.[0-9]+\.[0-9]+$`
- Version pattern: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-z0-9.-]+)?$` - Must include @username
#### `GET /services/:uuid` #### `GET /services/:fqn`
Get service details by UUID Get service by FQN - Three modes:
**Response:** **1. Direct Lookup (with username):**
```
GET /services/chat:1.0.0@alice
```
Returns first available offer from Alice's chat:1.0.0 service.
**2. Random Discovery (without username):**
```
GET /services/chat:1.0.0
```
Returns a random available offer from any user's chat:1.0.0 service.
**3. Paginated Discovery (with query params):**
```
GET /services/chat:1.0.0?limit=10&offset=0
```
Returns array of unique available offers from different users.
**Semver Matching:**
- Requesting `chat:1.0.0` matches any `1.x.x` version
- Major version must match exactly (`chat:1.0.0` will NOT match `chat:2.0.0`)
- For major version 0, minor must also match (`0.1.0` will NOT match `0.2.0`)
- Returns the most recently published compatible version
**Response (Single Offer):**
```json ```json
{ {
"serviceId": "...", "serviceId": "uuid",
"username": "alice", "username": "alice",
"serviceFqn": "com.example.chat@1.0.0", "serviceFqn": "chat:1.0.0@alice",
"offerId": "...", "offerId": "offer-hash",
"sdp": "v=0...", "sdp": "v=0...",
"isPublic": false,
"metadata": { ... },
"createdAt": 1733404800000, "createdAt": 1733404800000,
"expiresAt": 1733405100000 "expiresAt": 1733405100000
} }
``` ```
#### `DELETE /users/:username/services/:fqn` **Response (Paginated):**
```json
{
"services": [
{
"serviceId": "uuid",
"username": "alice",
"serviceFqn": "chat:1.0.0@alice",
"offerId": "offer-hash",
"sdp": "v=0...",
"createdAt": 1733404800000,
"expiresAt": 1733405100000
}
],
"count": 1,
"limit": 10,
"offset": 0
}
```
#### `DELETE /services/:fqn`
Unpublish a service (requires authentication and ownership) Unpublish a service (requires authentication and ownership)
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
**Request:** **Response:**
```json ```json
{ {
"username": "alice" "success": true
} }
``` ```
### WebRTC Signaling (Service-Based) ### WebRTC Signaling
#### `POST /services/:uuid/answer` #### `POST /services/:fqn/offers/:offerId/answer`
Answer a service offer (requires authentication) Post answer SDP to specific offer
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
@@ -263,8 +297,8 @@ Answer a service offer (requires authentication)
} }
``` ```
#### `GET /services/:uuid/answer` #### `GET /services/:fqn/offers/:offerId/answer`
Get answer for a service (offerer polls this) Get answer SDP (offerer polls this)
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
@@ -272,17 +306,77 @@ Get answer for a service (offerer polls this)
**Response:** **Response:**
```json ```json
{ {
"sdp": "v=0...",
"offerId": "offer-hash", "offerId": "offer-hash",
"answererId": "answerer-peer-id", "answererId": "answerer-peer-id",
"sdp": "v=0...",
"answeredAt": 1733404800000 "answeredAt": 1733404800000
} }
``` ```
**Note:** Returns 404 if not yet answered Returns 404 if not yet answered.
#### `POST /services/:uuid/ice-candidates` #### `GET /offers/answered`
Post ICE candidates for a service (requires authentication) Get all answered offers (efficient batch polling for offerer)
**Headers:**
- `Authorization: Bearer {peerId}:{secret}`
**Query params:**
- `since` - Optional timestamp to get only new answers
**Response:**
```json
{
"offers": [
{
"offerId": "offer-hash",
"serviceId": "service-uuid",
"answererId": "answerer-peer-id",
"sdp": "v=0...",
"answeredAt": 1733404800000
}
]
}
```
#### `GET /offers/poll`
Combined polling for answers and ICE candidates (offerer)
**Headers:**
- `Authorization: Bearer {peerId}:{secret}`
**Query params:**
- `since` - Optional timestamp to get only new data
**Response:**
```json
{
"answers": [
{
"offerId": "offer-hash",
"serviceId": "service-uuid",
"answererId": "answerer-peer-id",
"sdp": "v=0...",
"answeredAt": 1733404800000
}
],
"iceCandidates": {
"offer-hash": [
{
"candidate": { "candidate": "...", "sdpMid": "0", "sdpMLineIndex": 0 },
"role": "answerer",
"peerId": "peer-id",
"createdAt": 1733404800000
}
]
}
}
```
More efficient than polling answers and ICE separately - reduces HTTP requests by 50%.
#### `POST /services/:fqn/offers/:offerId/ice-candidates`
Add ICE candidates to specific offer
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
@@ -290,8 +384,13 @@ Post ICE candidates for a service (requires authentication)
**Request:** **Request:**
```json ```json
{ {
"candidates": ["candidate:1 1 UDP..."], "candidates": [
"offerId": "optional-offer-id" {
"candidate": "candidate:...",
"sdpMid": "0",
"sdpMLineIndex": 0
}
]
} }
``` ```
@@ -303,20 +402,25 @@ Post ICE candidates for a service (requires authentication)
} }
``` ```
**Note:** If `offerId` is omitted, the server will auto-detect the peer's offer #### `GET /services/:fqn/offers/:offerId/ice-candidates`
Get ICE candidates for specific offer
#### `GET /services/:uuid/ice-candidates?since=1234567890&offerId=optional-offer-id`
Get ICE candidates from the other peer (requires authentication)
**Headers:** **Headers:**
- `Authorization: Bearer {peerId}:{secret}` - `Authorization: Bearer {peerId}:{secret}`
**Query params:**
- `since` - Optional timestamp to get only new candidates
**Response:** **Response:**
```json ```json
{ {
"candidates": [ "candidates": [
{ {
"candidate": "candidate:1 1 UDP...", "candidate": {
"candidate": "candidate:...",
"sdpMid": "0",
"sdpMLineIndex": 0
},
"createdAt": 1733404800000 "createdAt": 1733404800000
} }
], ],
@@ -335,7 +439,7 @@ Environment variables:
| `PORT` | `3000` | Server port (Node.js/Docker) | | `PORT` | `3000` | Server port (Node.js/Docker) |
| `CORS_ORIGINS` | `*` | Comma-separated allowed origins | | `CORS_ORIGINS` | `*` | Comma-separated allowed origins |
| `STORAGE_PATH` | `./rondevu.db` | SQLite database path (use `:memory:` for in-memory) | | `STORAGE_PATH` | `./rondevu.db` | SQLite database path (use `:memory:` for in-memory) |
| `VERSION` | `2.0.0` | Server version (semver) | | `VERSION` | `0.4.0` | Server version (semver) |
| `AUTH_SECRET` | Random 32-byte hex | Secret key for credential encryption (required for production) | | `AUTH_SECRET` | Random 32-byte hex | Secret key for credential encryption (required for production) |
| `OFFER_DEFAULT_TTL` | `300000` | Default offer TTL in ms (5 minutes) | | `OFFER_DEFAULT_TTL` | `300000` | Default offer TTL in ms (5 minutes) |
| `OFFER_MIN_TTL` | `60000` | Minimum offer TTL in ms (1 minute) | | `OFFER_MIN_TTL` | `60000` | Minimum offer TTL in ms (1 minute) |
@@ -350,29 +454,34 @@ Environment variables:
- `claimed_at`: Claim timestamp - `claimed_at`: Claim timestamp
- `expires_at`: Expiry timestamp (365 days) - `expires_at`: Expiry timestamp (365 days)
- `last_used`: Last activity timestamp - `last_used`: Last activity timestamp
- `metadata`: Optional JSON metadata
### services ### services
- `id` (PK): Service ID (UUID) - `id` (PK): Service ID (UUID)
- `username` (FK): Owner username - `username` (FK): Owner username
- `service_fqn`: Fully qualified name (com.example.chat@1.0.0) - `service_fqn`: Fully qualified name (chat:1.0.0@alice)
- `is_public`: Public/private flag - `service_name`: Service name component (chat)
- `metadata`: JSON metadata - `version`: Version component (1.0.0)
- `created_at`, `expires_at`: Timestamps - `created_at`, `expires_at`: Timestamps
- UNIQUE constraint on (service_name, version, username)
### offers ### offers
- `id` (PK): Offer ID (hash of SDP) - `id` (PK): Offer ID (hash of SDP)
- `peer_id` (FK): Owner peer ID - `peer_id` (FK): Owner peer ID
- `service_id` (FK): Optional link to service (null for standalone offers) - `service_id` (FK): Link to service
- `service_fqn`: Denormalized service FQN
- `sdp`: WebRTC offer SDP - `sdp`: WebRTC offer SDP
- `answerer_peer_id`: Peer ID of answerer (null until answered) - `answerer_peer_id`: Peer ID of answerer (null until answered)
- `answer_sdp`: WebRTC answer SDP (null until answered) - `answer_sdp`: WebRTC answer SDP (null until answered)
- `created_at`, `expires_at`, `last_seen`: Timestamps - `answered_at`: Timestamp when answered
- `created_at`, `expires_at`: Timestamps
### service_index (privacy layer) ### ice_candidates
- `uuid` (PK): Random UUID for discovery - `id` (PK): Auto-increment ID
- `service_id` (FK): Links to service - `offer_id` (FK): Link to offer
- `username`, `service_fqn`: Denormalized for performance - `peer_id`: Peer who sent the candidate
- `role`: 'offerer' or 'answerer'
- `candidate`: JSON-encoded candidate
- `created_at`: Timestamp
## Security ## Security
@@ -387,18 +496,22 @@ Environment variables:
- **Message Format**: `publish:{username}:{serviceFqn}:{timestamp}` - **Message Format**: `publish:{username}:{serviceFqn}:{timestamp}`
- **Auto-Renewal**: Publishing a service extends username expiry - **Auto-Renewal**: Publishing a service extends username expiry
### Privacy ### ICE Candidate Filtering
- **Private Services**: Only UUID exposed, FQN hidden - Server filters candidates by role to prevent peers from receiving their own candidates
- **Public Services**: FQN and metadata visible - Offerers receive only answerer candidates
- **No Enumeration**: Cannot list all services without knowing FQN - Answerers receive only offerer candidates
## Migration from V1 ## Migration from v0.3.x
V2 is a **breaking change** that removes topic-based discovery. See [MIGRATION.md](../MIGRATION.md) for detailed migration guide. See [MIGRATION.md](../MIGRATION.md) for detailed migration guide.
**Key Changes:** **Key Changes:**
- ❌ Removed: Topic-based discovery, bloom filters, public peer listings - Service FQN format changed from `service@version` to `service:version@username`
- ✅ Added: Username claiming, service publishing, UUID-based privacy - Removed UUID privacy layer - direct FQN-based access
- Removed public/private service distinction
- Added service discovery (random and paginated)
- Added combined polling endpoint (/offers/poll)
- ICE candidate endpoints moved to offer-specific routes
## License ## License