@xtr-dev/rondevu-server 0.0.1 → 0.1.2

package/API.md

@@ -19,6 +19,33 @@ This allows multiple peers from the same application (origin) to discover each o
 
 ## GET `/`
 
+Returns server version information including the git commit hash used to build the server.
+
+### Response
+
+**Content-Type:** `application/json`
+
+**Success (200 OK):**
+```json
+{
+  "version": "a1b2c3d"
+}
+```
+
+**Notes:**
+- Returns the git commit hash from build time
+- Returns "unknown" if git information is not available
+
+### Example
+
+```bash
+curl -X GET http://localhost:3000/
+```
+
+---
+
+## GET `/topics`
+
 Lists all topics with the count of available peers for each (paginated). Returns only topics that have unanswered sessions.
 
 ### Request
@@ -70,13 +97,13 @@ Lists all topics with the count of available peers for each (paginated). Returns
 
 **Default pagination (page 1, limit 100):**
 ```bash
-curl -X GET http://localhost:3000/ \
+curl -X GET http://localhost:3000/topics \
   -H "Origin: https://example.com"
 ```
 
 **Custom pagination:**
 ```bash
-curl -X GET "http://localhost:3000/?page=2&limit=50" \
+curl -X GET "http://localhost:3000/topics?page=2&limit=50" \
   -H "Origin: https://example.com"
 ```
 
@@ -403,26 +430,29 @@ All endpoints may return the following error responses:
 
 ### Peer Discovery and Connection
 
-1. **Discover active topics:**
-   - GET `/` to see all topics and peer counts
+1. **Check server version (optional):**
+   - GET `/` to see server version information
+
+2. **Discover active topics:**
+   - GET `/topics` to see all topics and peer counts
    - Optional: paginate through results with `?page=2&limit=100`
 
-2. **Peer A announces availability:**
+3. **Peer A announces availability:**
    - POST `/:topic/offer` with peer identifier and signaling data
    - Receives a unique session code
 
-3. **Peer B discovers peers:**
+4. **Peer B discovers peers:**
    - GET `/:topic/sessions` to list available sessions in a topic
    - Filters out sessions with their own info to avoid self-connection
    - Selects a peer to connect to
 
-4. **Peer B initiates connection:**
+5. **Peer B initiates connection:**
    - POST `/answer` with the session code and their signaling data
 
-5. **Both peers exchange signaling information:**
+6. **Both peers exchange signaling information:**
    - POST `/answer` with additional signaling data as needed
    - POST `/poll` to retrieve signaling data from the other peer
 
-6. **Peer connection established**
+7. **Peer connection established**
    - Peers use exchanged signaling data to establish direct connection
    - Session automatically expires after configured timeout

package/CLAUDE.md

@@ -0,0 +1,47 @@
+# Rondevu Server Development Guidelines
+
+## WebRTC Signaling Best Practices
+
+### ICE Candidate Storage
+
+**IMPORTANT: Store ICE candidates as raw JSON without enforcing structure.**
+
+When handling ICE candidates in the signaling server:
+
+- ✅ **DO** store candidates as `JSON.stringify(candidate)` in the database
+- ✅ **DO** retrieve candidates as `JSON.parse(candidate)` from the database
+- ✅ **DO** use generic types like `any` in TypeScript for candidate data
+- ❌ **DON'T** define strict types for ICE candidate structure
+- ❌ **DON'T** validate or modify candidate properties
+- ❌ **DON'T** assume you know what properties clients will send
+
+**Why?** The server is just a relay - it doesn't need to understand the candidate structure. Different browsers and future WebRTC versions may include different properties. By keeping the server agnostic, we maintain maximum compatibility.
+
+### Server Role Filtering
+
+The server MUST filter ICE candidates by role:
+- Offerers receive only answerer candidates (`WHERE role = 'answerer'`)
+- Answerers receive only offerer candidates (`WHERE role = 'offerer'`)
+
+This prevents peers from receiving their own candidates, which would cause connection failures.
+
+## Security
+
+- Always validate authentication tokens before allowing operations
+- Verify ownership before allowing modifications
+- Rate limit API endpoints to prevent abuse
+- Clean up expired offers regularly
+
+## Performance
+
+- Use transactions for batch operations (SQLite)
+- Index frequently queried columns (offer_id, role, created_at)
+- Set appropriate TTLs for offers
+- Implement pagination for large result sets
+
+## Code Quality
+
+- Handle errors gracefully with informative HTTP status codes
+- Log important events for debugging
+- Use TypeScript types for API contracts, but keep data types generic
+- Write tests for critical paths

package/README.md

@@ -1,242 +1,199 @@
-# Rondevu
+# Rondevu Server
 
-An open signaling and tracking server for peer discovery. Enables peers to find each other through a topic-based HTTP API with Origin isolation for organizing peer-to-peer applications.
+[![npm version](https://img.shields.io/npm/v/@xtr-dev/rondevu-server)](https://www.npmjs.com/package/@xtr-dev/rondevu-server)
 
-## Features
-
-- 🚀 **Fast & Lightweight** - Built with [Hono](https://hono.dev/) framework
-- 📂 **Topic-Based Organization** - Group sessions by topic for easy peer discovery
-- 🔒 **Origin Isolation** - Sessions are isolated by HTTP Origin header to group topics by domain
-- 🏷️ **Peer Identification** - Info field prevents duplicate connections to same peer
-- 🔌 **Pluggable Storage** - Storage interface supports SQLite and in-memory adapters
-- 🐳 **Docker Ready** - Minimal Alpine-based Docker image
-- ⏱️ **Session Timeout** - Configurable session expiration from initiation time
-- 🔐 **Type Safe** - Written in TypeScript with full type definitions
+🌐 **Topic-based peer discovery and WebRTC signaling**
 
-## Quick Start
+Scalable peer-to-peer connection establishment with topic-based discovery, stateless authentication, and complete WebRTC signaling.
 
-### Using Node.js
+**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-server](https://github.com/xtr-dev/rondevu-server) - HTTP signaling server ([npm](https://www.npmjs.com/package/@xtr-dev/rondevu-server), [live](https://api.ronde.vu))
+- [@xtr-dev/rondevu-demo](https://github.com/xtr-dev/rondevu-demo) - Interactive demo ([live](https://ronde.vu))
 
-```bash
-# Install dependencies
-npm install
+---
 
-# Run in development mode
-npm run dev
+## Features
 
-# Build and run in production
-npm run build
-npm start
-```
+- **Topic-Based Discovery**: Tag offers with topics (e.g., torrent infohashes) for efficient peer finding
+- **Stateless Authentication**: AES-256-GCM encrypted credentials, no server-side sessions
+- **Protected Offers**: Optional secret field for access-controlled peer connections
+- **Bloom Filters**: Client-side peer exclusion for efficient discovery
+- **Multi-Offer Support**: Create multiple offers per peer simultaneously
+- **Complete WebRTC Signaling**: Offer/answer exchange and ICE candidate relay
+- **Dual Storage**: SQLite (Node.js/Docker) and Cloudflare D1 (Workers) backends
 
-### Using Docker
+## Quick Start
 
+**Node.js:**
 ```bash
-# Build the image
-docker build -t rondevu .
-
-# Run with default settings (SQLite database)
-docker run -p 3000:3000 rondevu
-
-# Run with in-memory storage
-docker run -p 3000:3000 -e STORAGE_TYPE=memory rondevu
-
-# Run with custom timeout (10 minutes)
-docker run -p 3000:3000 -e SESSION_TIMEOUT=600000 rondevu
+npm install && npm start
 ```
 
-### Using Cloudflare Workers
-
+**Docker:**
 ```bash
-# Install Wrangler CLI
-npm install -g wrangler
-
-# Login to Cloudflare
-wrangler login
-
-# Create KV namespace
-wrangler kv:namespace create SESSIONS
-
-# Update wrangler.toml with the KV namespace ID
+docker build -t rondevu . && docker run -p 3000:3000 -e STORAGE_PATH=:memory: rondevu
+```
 
-# Deploy to Cloudflare's edge network
+**Cloudflare Workers:**
+```bash
 npx wrangler deploy
 ```
 
-See [DEPLOYMENT.md](./DEPLOYMENT.md#cloudflare-workers) for detailed instructions.
+## API Endpoints
 
-## Configuration
+### Public Endpoints
 
-Configuration is done through environment variables:
+#### `GET /`
+Returns server version and info
 
-| Variable           | Description                                      | Default     |
-|--------------------|--------------------------------------------------|-------------|
-| `PORT`             | Server port                                      | `3000`      |
-| `STORAGE_TYPE`     | Storage backend: `sqlite` or `memory`            | `sqlite`    |
-| `STORAGE_PATH`     | Path to SQLite database file                     | `./data.db` |
-| `SESSION_TIMEOUT`  | Session timeout in milliseconds                  | `300000`    |
-| `CORS_ORIGINS`     | Comma-separated list of allowed origins          | `*`         |
+#### `GET /health`
+Health check endpoint with version
 
-### Example .env file
+#### `POST /register`
+Register a new peer and receive credentials (peerId + secret)
 
-```env
-PORT=3000
-STORAGE_TYPE=sqlite
-STORAGE_PATH=./sessions.db
-SESSION_TIMEOUT=300000
-CORS_ORIGINS=https://example.com,https://app.example.com
+**Response:**
+```json
+{
+  "peerId": "f17c195f067255e357232e34cf0735d9",
+  "secret": "DdorTR8QgSn9yngn+4qqR8cs1aMijvX..."
+}
 ```
 
-## API Documentation
-
-See [API.md](./API.md) for complete API documentation.
-
-### Quick Overview
-
-**List all active topics (with pagination):**
-```bash
-curl -X GET http://localhost:3000/ \
-  -H "Origin: https://example.com"
-# Returns: {"topics":[{"topic":"my-room","count":3}],"pagination":{...}}
+#### `GET /topics?limit=50&offset=0`
+List all topics with active peer counts (paginated)
+
+**Query Parameters:**
+- `limit` (optional): Maximum number of topics to return (default: 50, max: 200)
+- `offset` (optional): Number of topics to skip (default: 0)
+
+**Response:**
+```json
+{
+  "topics": [
+    {"topic": "movie-xyz", "activePeers": 42},
+    {"topic": "torrent-abc", "activePeers": 15}
+  ],
+  "total": 123,
+  "limit": 50,
+  "offset": 0
+}
 ```
 
-**Create an offer (announce yourself as available):**
-```bash
-curl -X POST http://localhost:3000/my-room/offer \
-  -H "Content-Type: application/json" \
-  -H "Origin: https://example.com" \
-  -d '{"info":"peer-123","offer":"<SIGNALING_DATA>"}'
-# Returns: {"code":"550e8400-e29b-41d4-a716-446655440000"}
+#### `GET /offers/by-topic/:topic?limit=50&bloom=...`
+Find offers by topic with optional bloom filter exclusion
+
+**Query Parameters:**
+- `limit` (optional): Maximum offers to return (default: 50, max: 200)
+- `bloom` (optional): Base64-encoded bloom filter to exclude known peers
+
+**Response:**
+```json
+{
+  "topic": "movie-xyz",
+  "offers": [
+    {
+      "id": "offer-id",
+      "peerId": "peer-id",
+      "sdp": "v=0...",
+      "topics": ["movie-xyz", "hd-content"],
+      "expiresAt": 1234567890,
+      "lastSeen": 1234567890,
+      "hasSecret": true  // Indicates if secret is required to answer
+    }
+  ],
+  "total": 42,
+  "returned": 10
+}
 ```
 
-**List available peers in a topic:**
-```bash
-curl -X GET http://localhost:3000/my-room/sessions \
-  -H "Origin: https://example.com"
-# Returns: {"sessions":[...]}
-```
+**Notes:**
+- `hasSecret`: Boolean flag indicating whether a secret is required to answer this offer. The actual secret is never exposed in public endpoints.
 
-**Connect to a peer:**
-```bash
-curl -X POST http://localhost:3000/answer \
-  -H "Content-Type: application/json" \
-  -H "Origin: https://example.com" \
-  -d '{"code":"550e8400-...","answer":"<SIGNALING_DATA>","side":"answerer"}'
-# Returns: {"success":true}
-```
+#### `GET /peers/:peerId/offers`
+View all offers from a specific peer
 
-## Architecture
+### Authenticated Endpoints
 
-### Storage Interface
+All authenticated endpoints require `Authorization: Bearer {peerId}:{secret}` header.
 
-The storage layer is abstracted through a simple interface, making it easy to implement custom storage backends:
+#### `POST /offers`
+Create one or more offers
 
-```typescript
-interface Storage {
-  createSession(origin: string, topic: string, info: string, offer: string, expiresAt: number): Promise<string>;
-  listSessionsByTopic(origin: string, topic: string): Promise<Session[]>;
-  getSession(code: string, origin: string): Promise<Session | null>;
-  updateSession(code: string, origin: string, update: Partial<Session>): Promise<void>;
-  deleteSession(code: string): Promise<void>;
-  cleanup(): Promise<void>;
-  close(): Promise<void>;
+**Request:**
+```json
+{
+  "offers": [
+    {
+      "sdp": "v=0...",
+      "topics": ["movie-xyz", "hd-content"],
+      "ttl": 300000,
+      "secret": "my-secret-password"  // Optional: protect offer (max 128 chars)
+    }
+  ]
 }
 ```
 
-### Built-in Storage Adapters
+**Notes:**
+- `secret` (optional): Protect the offer with a secret. Answerers must provide the correct secret to connect.
 
-**SQLite Storage** (`sqlite.ts`)
-- For Node.js/Docker deployments
-- Persistent file-based or in-memory
-- Automatic session cleanup
-- Simple and reliable
+#### `GET /offers/mine`
+List all offers owned by authenticated peer
 
-**Cloudflare KV Storage** (`kv.ts`)
-- For Cloudflare Workers deployments
-- Global edge storage
-- Automatic TTL-based expiration
-- Distributed and highly available
+#### `PUT /offers/:offerId/heartbeat`
+Update last_seen timestamp for an offer
 
-### Custom Storage Adapters
+#### `DELETE /offers/:offerId`
+Delete a specific offer
 
-You can implement your own storage adapter by implementing the `Storage` interface:
+#### `POST /offers/:offerId/answer`
+Answer an offer (locks it to answerer)
 
-```typescript
-import { Storage, Session } from './storage/types';
-
-export class CustomStorage implements Storage {
-  async createSession(offer: string, expiresAt: number): Promise<string> {
-    // Your implementation
-  }
-  // ... implement other methods
+**Request:**
+```json
+{
+  "sdp": "v=0...",
+  "secret": "my-secret-password"  // Required if offer is protected
 }
 ```
 
-## Development
-
-### Project Structure
-
-```
-rondevu/
-├── src/
-│   ├── index.ts           # Node.js server entry point
-│   ├── app.ts             # Hono application
-│   ├── config.ts          # Configuration
-│   └── storage/
-│       ├── types.ts       # Storage interface
-│       ├── sqlite.ts      # SQLite adapter
-│       └── codeGenerator.ts  # Code generation utility
-├── Dockerfile             # Docker build configuration
-├── build.js               # Build script
-├── API.md                 # API documentation
-└── README.md              # This file
-```
+**Notes:**
+- `secret` (optional): Required if the offer was created with a secret. Must match the offer's secret.
 
-### Building
+#### `GET /offers/answers`
+Poll for answers to your offers
 
-```bash
-# Build TypeScript
-npm run build
+#### `POST /offers/:offerId/ice-candidates`
+Post ICE candidates for an offer
 
-# Run built version
-npm start
-```
-
-### Docker Build
-
-```bash
-# Build the image
-docker build -t rondevu .
-
-# Run with volume for persistent storage
-docker run -p 3000:3000 -v $(pwd)/data:/app/data rondevu
+**Request:**
+```json
+{
+  "candidates": ["candidate:1 1 UDP..."]
+}
 ```
 
-## How It Works
+#### `GET /offers/:offerId/ice-candidates?since=1234567890`
+Get ICE candidates from the other peer
 
-1. **Discover topics** (optional): Call `GET /` to see all active topics and peer counts
-2. **Peer A** announces availability by posting to `/:topic/offer` with peer identifier and signaling data
-3. Server generates a unique UUID code and stores the session (bucketed by Origin and topic)
-4. **Peer B** discovers available peers using `GET /:topic/sessions`
-5. **Peer B** filters out their own session using the info field to avoid self-connection
-6. **Peer B** selects a peer and posts their connection data to `POST /answer` with the session code
-7. Both peers exchange signaling data through `POST /answer` endpoint
-8. Both peers poll for updates using `POST /poll` to retrieve connection information
-9. Sessions automatically expire after the configured timeout
-
-This allows peers in distributed systems to discover each other without requiring a centralized registry, while maintaining isolation between different applications through Origin headers.
-
-### Origin Isolation
+## Configuration
 
-Sessions are isolated by the HTTP `Origin` header, ensuring that:
-- Peers can only see sessions from their own origin
-- Session codes cannot be accessed cross-origin
-- Topics are organized by application domain
+Environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port (Node.js/Docker) |
+| `CORS_ORIGINS` | `*` | Comma-separated allowed origins |
+| `STORAGE_PATH` | `./rondevu.db` | SQLite database path (use `:memory:` for in-memory) |
+| `VERSION` | `0.4.0` | Server version (semver) |
+| `AUTH_SECRET` | Random 32-byte hex | Secret key for credential encryption |
+| `OFFER_DEFAULT_TTL` | `300000` | Default offer TTL in ms (5 minutes) |
+| `OFFER_MIN_TTL` | `60000` | Minimum offer TTL in ms (1 minute) |
+| `OFFER_MAX_TTL` | `3600000` | Maximum offer TTL in ms (1 hour) |
+| `MAX_OFFERS_PER_REQUEST` | `10` | Maximum offers per create request |
+| `MAX_TOPICS_PER_OFFER` | `20` | Maximum topics per offer |
 
 ## License
 
 MIT
-
-## Contributing
-
-Contributions are welcome! Please feel free to submit a Pull Request.

package/build.js

@@ -1,5 +1,14 @@
 // Build script using esbuild
 const esbuild = require('esbuild');
+const { execSync } = require('child_process');
+
+// Get git commit hash
+let version = 'unknown';
+try {
+  version = execSync('git rev-parse --short HEAD', { encoding: 'utf8' }).trim();
+} catch (err) {
+  console.warn('Could not get git commit hash, using "unknown"');
+}
 
 esbuild.build({
   entryPoints: ['src/index.ts'],
@@ -14,4 +23,7 @@ esbuild.build({
     'hono'
   ],
   sourcemap: true,
+  define: {
+    'process.env.RONDEVU_VERSION': JSON.stringify(version)
+  }
 }).catch(() => process.exit(1));