@xtr-dev/rondevu-server 0.0.1 → 0.1.1

package/src/storage/types.ts

@@ -1,87 +1,161 @@
 /**
- * Represents a WebRTC signaling session
+ * Represents a WebRTC signaling offer with topic-based discovery
  */
-export interface Session {
-  code: string;
-  origin: string;
-  topic: string;
-  info: string;
-  offer: string;
-  answer?: string;
-  offerCandidates: string[];
-  answerCandidates: string[];
+export interface Offer {
+  id: string;
+  peerId: string;
+  sdp: string;
+  topics: string[];
   createdAt: number;
   expiresAt: number;
+  lastSeen: number;
+  secret?: string;
+  answererPeerId?: string;
+  answerSdp?: string;
+  answeredAt?: number;
+}
+
+/**
+ * Represents an ICE candidate for WebRTC signaling
+ * Stores the complete candidate object as plain JSON (no type enforcement)
+ */
+export interface IceCandidate {
+  id: number;
+  offerId: string;
+  peerId: string;
+  role: 'offerer' | 'answerer';
+  candidate: any; // Full candidate object as JSON - don't enforce structure
+  createdAt: number;
 }
 
 /**
- * Storage interface for session management
- * Implementations can use different backends (SQLite, Redis, Memory, etc.)
+ * Represents a topic with active peer count
+ */
+export interface TopicInfo {
+  topic: string;
+  activePeers: number;
+}
+
+/**
+ * Request to create a new offer
+ */
+export interface CreateOfferRequest {
+  id?: string;
+  peerId: string;
+  sdp: string;
+  topics: string[];
+  expiresAt: number;
+  secret?: string;
+}
+
+/**
+ * Storage interface for offer management with topic-based discovery
+ * Implementations can use different backends (SQLite, D1, Memory, etc.)
  */
 export interface Storage {
   /**
-   * Creates a new session with the given offer
-   * @param origin The Origin header from the request
-   * @param topic The topic to post the offer to
-   * @param info User info string (max 1024 chars)
-   * @param offer The WebRTC SDP offer message
-   * @param expiresAt Unix timestamp when the session should expire
-   * @returns The unique session code
+   * Creates one or more offers
+   * @param offers Array of offer creation requests
+   * @returns Array of created offers with IDs
+   */
+  createOffers(offers: CreateOfferRequest[]): Promise<Offer[]>;
+
+  /**
+   * Retrieves offers by topic with optional peer ID exclusion
+   * @param topic Topic to search for
+   * @param excludePeerIds Optional array of peer IDs to exclude
+   * @returns Array of offers matching the topic
+   */
+  getOffersByTopic(topic: string, excludePeerIds?: string[]): Promise<Offer[]>;
+
+  /**
+   * Retrieves all offers from a specific peer
+   * @param peerId Peer identifier
+   * @returns Array of offers from the peer
    */
-  createSession(origin: string, topic: string, info: string, offer: string, expiresAt: number): Promise<string>;
+  getOffersByPeerId(peerId: string): Promise<Offer[]>;
 
   /**
-   * Lists all unanswered sessions for a given origin and topic
-   * @param origin The Origin header from the request
-   * @param topic The topic to list offers for
-   * @returns Array of sessions that haven't been answered yet
+   * Retrieves a specific offer by ID
+   * @param offerId Offer identifier
+   * @returns The offer if found, null otherwise
    */
-  listSessionsByTopic(origin: string, topic: string): Promise<Session[]>;
+  getOfferById(offerId: string): Promise<Offer | null>;
 
   /**
-   * Lists all topics for a given origin with their session counts
-   * @param origin The Origin header from the request
-   * @param page Page number (starting from 1)
-   * @param limit Number of results per page (max 1000)
-   * @returns Object with topics array and pagination metadata
+   * Deletes an offer (with ownership verification)
+   * @param offerId Offer identifier
+   * @param ownerPeerId Peer ID of the owner (for verification)
+   * @returns true if deleted, false if not found or not owned
    */
-  listTopics(origin: string, page: number, limit: number): Promise<{
-    topics: Array<{ topic: string; count: number }>;
-    pagination: {
-      page: number;
-      limit: number;
-      total: number;
-      hasMore: boolean;
-    };
+  deleteOffer(offerId: string, ownerPeerId: string): Promise<boolean>;
+
+  /**
+   * Deletes all expired offers
+   * @param now Current timestamp
+   * @returns Number of offers deleted
+   */
+  deleteExpiredOffers(now: number): Promise<number>;
+
+  /**
+   * Answers an offer (locks it to the answerer)
+   * @param offerId Offer identifier
+   * @param answererPeerId Answerer's peer ID
+   * @param answerSdp WebRTC answer SDP
+   * @param secret Optional secret for protected offers
+   * @returns Success status and optional error message
+   */
+  answerOffer(offerId: string, answererPeerId: string, answerSdp: string, secret?: string): Promise<{
+    success: boolean;
+    error?: string;
   }>;
 
   /**
-   * Retrieves a session by its code
-   * @param code The session code
-   * @param origin The Origin header from the request (for validation)
-   * @returns The session if found, null otherwise
+   * Retrieves all answered offers for a specific offerer
+   * @param offererPeerId Offerer's peer ID
+   * @returns Array of answered offers
    */
-  getSession(code: string, origin: string): Promise<Session | null>;
+  getAnsweredOffers(offererPeerId: string): Promise<Offer[]>;
 
   /**
-   * Updates an existing session with new data
-   * @param code The session code
-   * @param origin The Origin header from the request (for validation)
-   * @param update Partial session data to update
+   * Adds ICE candidates for an offer
+   * @param offerId Offer identifier
+   * @param peerId Peer ID posting the candidates
+   * @param role Role of the peer (offerer or answerer)
+   * @param candidates Array of candidate objects (stored as plain JSON)
+   * @returns Number of candidates added
    */
-  updateSession(code: string, origin: string, update: Partial<Session>): Promise<void>;
+  addIceCandidates(
+    offerId: string,
+    peerId: string,
+    role: 'offerer' | 'answerer',
+    candidates: any[]
+  ): Promise<number>;
 
   /**
-   * Deletes a session
-   * @param code The session code
+   * Retrieves ICE candidates for an offer
+   * @param offerId Offer identifier
+   * @param targetRole Role to retrieve candidates for (offerer or answerer)
+   * @param since Optional timestamp - only return candidates after this time
+   * @returns Array of ICE candidates
    */
-  deleteSession(code: string): Promise<void>;
+  getIceCandidates(
+    offerId: string,
+    targetRole: 'offerer' | 'answerer',
+    since?: number
+  ): Promise<IceCandidate[]>;
 
   /**
-   * Removes expired sessions
-   * Should be called periodically to clean up old data
+   * Retrieves topics with active peer counts (paginated)
+   * @param limit Maximum number of topics to return
+   * @param offset Number of topics to skip
+   * @param startsWith Optional prefix filter - only return topics starting with this string
+   * @returns Object with topics array and total count
    */
-  cleanup(): Promise<void>;
+  getTopics(limit: number, offset: number, startsWith?: string): Promise<{
+    topics: TopicInfo[];
+    total: number;
+  }>;
 
   /**
    * Closes the storage connection and releases resources

package/src/worker.ts

@@ -1,13 +1,21 @@
 import { createApp } from './app.ts';
-import { KVStorage } from './storage/kv.ts';
+import { D1Storage } from './storage/d1.ts';
+import { generateSecretKey } from './crypto.ts';
+import { Config } from './config.ts';
 
 /**
  * Cloudflare Workers environment bindings
  */
 export interface Env {
-  SESSIONS: KVNamespace;
-  SESSION_TIMEOUT?: string;
+  DB: D1Database;
+  AUTH_SECRET?: string;
+  OFFER_DEFAULT_TTL?: string;
+  OFFER_MAX_TTL?: string;
+  OFFER_MIN_TTL?: string;
+  MAX_OFFERS_PER_REQUEST?: string;
+  MAX_TOPICS_PER_OFFER?: string;
   CORS_ORIGINS?: string;
+  VERSION?: string;
 }
 
 /**
@@ -15,25 +23,52 @@ export interface Env {
  */
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
-    // Initialize KV storage
-    const storage = new KVStorage(env.SESSIONS);
+    // Initialize D1 storage
+    const storage = new D1Storage(env.DB);
 
-    // Parse configuration
-    const sessionTimeout = env.SESSION_TIMEOUT
-      ? parseInt(env.SESSION_TIMEOUT, 10)
-      : 300000; // 5 minutes default
+    // Generate or use provided auth secret
+    const authSecret = env.AUTH_SECRET || generateSecretKey();
 
-    const corsOrigins = env.CORS_ORIGINS
-      ? env.CORS_ORIGINS.split(',').map(o => o.trim())
-      : ['*'];
+    // Build config from environment
+    const config: Config = {
+      port: 0, // Not used in Workers
+      storageType: 'sqlite', // D1 is SQLite-compatible
+      storagePath: '', // Not used with D1
+      corsOrigins: env.CORS_ORIGINS
+        ? env.CORS_ORIGINS.split(',').map(o => o.trim())
+        : ['*'],
+      version: env.VERSION || 'unknown',
+      authSecret,
+      offerDefaultTtl: env.OFFER_DEFAULT_TTL ? parseInt(env.OFFER_DEFAULT_TTL, 10) : 60000,
+      offerMaxTtl: env.OFFER_MAX_TTL ? parseInt(env.OFFER_MAX_TTL, 10) : 86400000,
+      offerMinTtl: env.OFFER_MIN_TTL ? parseInt(env.OFFER_MIN_TTL, 10) : 60000,
+      cleanupInterval: 60000, // Not used in Workers (scheduled handler instead)
+      maxOffersPerRequest: env.MAX_OFFERS_PER_REQUEST ? parseInt(env.MAX_OFFERS_PER_REQUEST, 10) : 100,
+      maxTopicsPerOffer: env.MAX_TOPICS_PER_OFFER ? parseInt(env.MAX_TOPICS_PER_OFFER, 10) : 50,
+    };
 
     // Create Hono app
-    const app = createApp(storage, {
-      sessionTimeout,
-      corsOrigins,
-    });
+    const app = createApp(storage, config);
 
     // Handle request
     return app.fetch(request, env, ctx);
   },
+
+  /**
+   * Scheduled handler for cron triggers
+   * Runs periodically to clean up expired offers
+   */
+  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
+    const storage = new D1Storage(env.DB);
+    const now = Date.now();
+
+    try {
+      // Delete expired offers
+      const deletedCount = await storage.deleteExpiredOffers(now);
+
+      console.log(`Cleaned up ${deletedCount} expired offers at ${new Date(now).toISOString()}`);
+    } catch (error) {
+      console.error('Error cleaning up offers:', error);
+    }
+  },
 };

package/wrangler.toml

@@ -0,0 +1,45 @@
+name = "rondevu"
+main = "src/worker.ts"
+compatibility_date = "2024-01-01"
+compatibility_flags = ["nodejs_compat"]
+
+# D1 Database binding
+[[d1_databases]]
+binding = "DB"
+database_name = "rondevu-offers"
+database_id = "b94e3f71-816d-455b-a89d-927fa49532d0"
+
+# Environment variables
+[vars]
+OFFER_DEFAULT_TTL = "60000"  # Default offer TTL: 1 minute
+OFFER_MAX_TTL = "86400000"  # Max offer TTL: 24 hours
+OFFER_MIN_TTL = "60000"  # Min offer TTL: 1 minute
+MAX_OFFERS_PER_REQUEST = "100"  # Max offers per request
+MAX_TOPICS_PER_OFFER = "50"  # Max topics per offer
+CORS_ORIGINS = "*"  # Comma-separated list of allowed origins
+VERSION = "0.1.0"  # Semantic version
+
+# AUTH_SECRET should be set as a secret, not a var
+# Run: npx wrangler secret put AUTH_SECRET
+# Enter a 64-character hex string (32 bytes)
+
+# Build configuration
+[build]
+command = ""
+
+# For local development:
+# Run: npx wrangler dev
+# The local D1 database will be created automatically
+
+# For production deployment:
+# 1. Create D1 database: npx wrangler d1 create rondevu-sessions
+# 2. Update the 'database_id' field above with the returned ID
+# 3. Initialize schema: npx wrangler d1 execute rondevu-sessions --remote --file=./migrations/schema.sql
+# 4. Deploy: npx wrangler deploy
+
+[observability]
+[observability.logs]
+enabled = false
+head_sampling_rate = 1
+invocation_logs = true
+persist = true

package/DEPLOYMENT.md

@@ -1,346 +0,0 @@
-# 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