@xtr-dev/rondevu-server 0.0.1

package/DEPLOYMENT.md

@@ -0,0 +1,346 @@
+# Deployment Guide
+
+This guide covers deploying Rondevu to various platforms.
+
+## Table of Contents
+
+- [Cloudflare Workers](#cloudflare-workers)
+- [Docker](#docker)
+- [Node.js](#nodejs)
+
+---
+
+## Cloudflare Workers
+
+Deploy to Cloudflare's edge network using Cloudflare Workers and KV storage.
+
+### Prerequisites
+
+```bash
+npm install -g wrangler
+```
+
+### Setup
+
+1. **Login to Cloudflare**
+   ```bash
+   wrangler login
+   ```
+
+2. **Create KV Namespace**
+   ```bash
+   # For production
+   wrangler kv:namespace create SESSIONS
+
+   # This will output something like:
+   # { binding = "SESSIONS", id = "abc123..." }
+   ```
+
+3. **Update wrangler.toml**
+
+   Edit `wrangler.toml` and replace `YOUR_KV_NAMESPACE_ID` with the ID from step 2:
+
+   ```toml
+   [[kv_namespaces]]
+   binding = "SESSIONS"
+   id = "abc123..."  # Your actual KV namespace ID
+   ```
+
+4. **Configure Environment Variables** (Optional)
+
+   Update `wrangler.toml` to customize settings:
+
+   ```toml
+   [vars]
+   SESSION_TIMEOUT = "300000"  # Session timeout in milliseconds
+   CORS_ORIGINS = "https://example.com,https://app.example.com"
+   ```
+
+### Local Development
+
+```bash
+# Run locally with Wrangler
+npx wrangler dev
+
+# The local development server will:
+# - Start on http://localhost:8787
+# - Use a local KV namespace automatically
+# - Hot-reload on file changes
+```
+
+### Production Deployment
+
+```bash
+# Deploy to Cloudflare Workers
+npx wrangler deploy
+
+# This will output your worker URL:
+# https://rondevu.YOUR_SUBDOMAIN.workers.dev
+```
+
+### Custom Domain (Optional)
+
+1. Go to your Cloudflare Workers dashboard
+2. Select your worker
+3. Click "Triggers" → "Add Custom Domain"
+4. Enter your domain (e.g., `api.example.com`)
+
+### Monitoring
+
+View logs and analytics:
+
+```bash
+# Stream real-time logs
+npx wrangler tail
+
+# View in dashboard
+# Visit: https://dash.cloudflare.com → Workers & Pages
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SESSION_TIMEOUT` | `300000` | Session timeout in milliseconds |
+| `CORS_ORIGINS` | `*` | Comma-separated allowed origins |
+
+### Pricing
+
+Cloudflare Workers Free Tier includes:
+- 100,000 requests/day
+- 10ms CPU time per request
+- KV: 100,000 reads/day, 1,000 writes/day
+
+For higher usage, see [Cloudflare Workers pricing](https://workers.cloudflare.com/#plans).
+
+### Advantages
+
+- **Global Edge Network**: Deploy to 300+ locations worldwide
+- **Instant Scaling**: Handles traffic spikes automatically
+- **Low Latency**: Runs close to your users
+- **No Server Management**: Fully serverless
+- **Free Tier**: Generous limits for small projects
+
+---
+
+## Docker
+
+### Quick Start
+
+```bash
+# Build
+docker build -t rondevu .
+
+# Run with in-memory SQLite
+docker run -p 3000:3000 -e STORAGE_PATH=:memory: rondevu
+
+# Run with persistent SQLite
+docker run -p 3000:3000 \
+  -v $(pwd)/data:/app/data \
+  -e STORAGE_PATH=/app/data/sessions.db \
+  rondevu
+```
+
+### Docker Compose
+
+Create a `docker-compose.yml`:
+
+```yaml
+version: '3.8'
+
+services:
+  rondevu:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - PORT=3000
+      - STORAGE_TYPE=sqlite
+      - STORAGE_PATH=/app/data/sessions.db
+      - SESSION_TIMEOUT=300000
+      - CORS_ORIGINS=*
+    volumes:
+      - ./data:/app/data
+    restart: unless-stopped
+```
+
+Run with:
+```bash
+docker-compose up -d
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `STORAGE_TYPE` | `sqlite` | Storage backend |
+| `STORAGE_PATH` | `/app/data/sessions.db` | SQLite database path |
+| `SESSION_TIMEOUT` | `300000` | Session timeout in ms |
+| `CORS_ORIGINS` | `*` | Allowed CORS origins |
+
+---
+
+## Node.js
+
+### Production Deployment
+
+1. **Install Dependencies**
+   ```bash
+   npm ci --production
+   ```
+
+2. **Build TypeScript**
+   ```bash
+   npm run build
+   ```
+
+3. **Set Environment Variables**
+   ```bash
+   export PORT=3000
+   export STORAGE_TYPE=sqlite
+   export STORAGE_PATH=./data/sessions.db
+   export SESSION_TIMEOUT=300000
+   export CORS_ORIGINS=*
+   ```
+
+4. **Run**
+   ```bash
+   npm start
+   ```
+
+### Process Manager (PM2)
+
+For production, use a process manager like PM2:
+
+1. **Install PM2**
+   ```bash
+   npm install -g pm2
+   ```
+
+2. **Create ecosystem.config.js**
+   ```javascript
+   module.exports = {
+     apps: [{
+       name: 'rondevu',
+       script: './dist/index.js',
+       instances: 'max',
+       exec_mode: 'cluster',
+       env: {
+         NODE_ENV: 'production',
+         PORT: 3000,
+         STORAGE_TYPE: 'sqlite',
+         STORAGE_PATH: './data/sessions.db',
+         SESSION_TIMEOUT: 300000,
+         CORS_ORIGINS: '*'
+       }
+     }]
+   };
+   ```
+
+3. **Start with PM2**
+   ```bash
+   pm2 start ecosystem.config.js
+   pm2 save
+   pm2 startup
+   ```
+
+### Systemd Service
+
+Create `/etc/systemd/system/rondevu.service`:
+
+```ini
+[Unit]
+Description=Rondevu Peer Discovery and Signaling Server
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+WorkingDirectory=/opt/rondevu
+ExecStart=/usr/bin/node dist/index.js
+Restart=on-failure
+Environment=PORT=3000
+Environment=STORAGE_TYPE=sqlite
+Environment=STORAGE_PATH=/opt/rondevu/data/sessions.db
+Environment=SESSION_TIMEOUT=300000
+Environment=CORS_ORIGINS=*
+
+[Install]
+WantedBy=multi-user.target
+```
+
+Enable and start:
+```bash
+sudo systemctl enable rondevu
+sudo systemctl start rondevu
+sudo systemctl status rondevu
+```
+
+---
+
+## Troubleshooting
+
+### Docker
+
+**Issue: Permission denied on /app/data**
+- Ensure volume permissions are correct
+- The container runs as user `node` (UID 1000)
+
+**Issue: Database locked**
+- Don't share the same SQLite database file across multiple containers
+- Use one instance or implement a different storage backend
+
+### Node.js
+
+**Issue: EADDRINUSE**
+- Port is already in use, change `PORT` environment variable
+
+**Issue: Database is locked**
+- Another process is using the database
+- Ensure only one instance is running with the same database file
+
+---
+
+## Performance Tuning
+
+### Node.js/Docker
+
+- Set `SESSION_TIMEOUT` appropriately to balance resource usage
+- For high traffic, use `STORAGE_PATH=:memory:` with session replication
+- Consider horizontal scaling with a shared database backend
+
+---
+
+## Security Considerations
+
+1. **HTTPS**: Always use HTTPS in production
+   - Use a reverse proxy (nginx, Caddy) for Node.js deployments
+   - Docker deployments should be behind a reverse proxy
+
+2. **Rate Limiting**: Implement rate limiting at the proxy level
+
+3. **CORS**: Configure CORS origins appropriately
+   - Don't use `*` in production
+   - Set specific allowed origins: `https://example.com,https://app.example.com`
+
+4. **Input Validation**: SDP offers/answers are stored as-is; validate on client side
+
+5. **Session Codes**: UUID v4 codes provide strong entropy (2^122 combinations)
+
+6. **Origin Isolation**: Sessions are isolated by Origin header to organize topics by domain
+
+---
+
+## Scaling
+
+### Horizontal Scaling
+
+- **Docker/Node.js**: Use a shared database (not SQLite) for multiple instances
+  - Implement a Redis or PostgreSQL storage adapter
+
+### Vertical Scaling
+
+- Increase `SESSION_TIMEOUT` or cleanup frequency as needed
+- Monitor database size and connection pool
+- For Node.js, monitor memory usage and increase if needed

package/Dockerfile

@@ -0,0 +1,57 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source files
+COPY tsconfig.json ./
+COPY build.js ./
+COPY src ./src
+
+# Build TypeScript
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install production dependencies only
+COPY package*.json ./
+RUN npm ci --omit=dev && \
+    npm cache clean --force
+
+# Copy built files from builder
+COPY --from=builder /app/dist ./dist
+
+# Create data directory for SQLite
+RUN mkdir -p /app/data && \
+    chown -R node:node /app
+
+# Switch to non-root user
+USER node
+
+# Environment variables with defaults
+ENV PORT=3000
+ENV STORAGE_TYPE=sqlite
+ENV STORAGE_PATH=/app/data/sessions.db
+ENV SESSION_TIMEOUT=300000
+ENV CODE_CHARS=0123456789
+ENV CODE_LENGTH=9
+ENV CORS_ORIGINS=*
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:${PORT}/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
+
+# Start server
+CMD ["node", "dist/index.js"]

package/README.md

@@ -0,0 +1,242 @@
+# Rondevu
+
+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.
+
+## 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
+
+## Quick Start
+
+### Using Node.js
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build and run in production
+npm run build
+npm start
+```
+
+### Using Docker
+
+```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
+```
+
+### Using Cloudflare Workers
+
+```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
+
+# Deploy to Cloudflare's edge network
+npx wrangler deploy
+```
+
+See [DEPLOYMENT.md](./DEPLOYMENT.md#cloudflare-workers) for detailed instructions.
+
+## Configuration
+
+Configuration is done through environment variables:
+
+| 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          | `*`         |
+
+### Example .env file
+
+```env
+PORT=3000
+STORAGE_TYPE=sqlite
+STORAGE_PATH=./sessions.db
+SESSION_TIMEOUT=300000
+CORS_ORIGINS=https://example.com,https://app.example.com
+```
+
+## 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":{...}}
+```
+
+**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"}
+```
+
+**List available peers in a topic:**
+```bash
+curl -X GET http://localhost:3000/my-room/sessions \
+  -H "Origin: https://example.com"
+# Returns: {"sessions":[...]}
+```
+
+**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}
+```
+
+## Architecture
+
+### Storage Interface
+
+The storage layer is abstracted through a simple interface, making it easy to implement custom storage backends:
+
+```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>;
+}
+```
+
+### Built-in Storage Adapters
+
+**SQLite Storage** (`sqlite.ts`)
+- For Node.js/Docker deployments
+- Persistent file-based or in-memory
+- Automatic session cleanup
+- Simple and reliable
+
+**Cloudflare KV Storage** (`kv.ts`)
+- For Cloudflare Workers deployments
+- Global edge storage
+- Automatic TTL-based expiration
+- Distributed and highly available
+
+### Custom Storage Adapters
+
+You can implement your own storage adapter by implementing the `Storage` interface:
+
+```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
+}
+```
+
+## 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
+```
+
+### Building
+
+```bash
+# Build TypeScript
+npm run build
+
+# 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
+```
+
+## How It Works
+
+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
+
+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
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/build.js

@@ -0,0 +1,17 @@
+// Build script using esbuild
+const esbuild = require('esbuild');
+
+esbuild.build({
+  entryPoints: ['src/index.ts'],
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  outfile: 'dist/index.js',
+  format: 'cjs',
+  external: [
+    'better-sqlite3',
+    '@hono/node-server',
+    'hono'
+  ],
+  sourcemap: true,
+}).catch(() => process.exit(1));