From 4345709e9c09fee6bd1084eff75e181d56c12527 Mon Sep 17 00:00:00 2001 From: Bas van den Aakster Date: Fri, 12 Dec 2025 22:43:48 +0100 Subject: [PATCH] Remove RondevuSignaler documentation and outdated files - Remove entire RondevuSignaler class documentation section - Remove PollingConfig interface from Types section - Delete obsolete USAGE.md file (completely outdated) - Update all examples to use new automatic API - Fix migration examples to show current publishService() format --- README.md | 120 +++-------------------- USAGE.md | 281 ------------------------------------------------------ 2 files changed, 13 insertions(+), 388 deletions(-) delete mode 100644 USAGE.md diff --git a/README.md b/README.md index 5f6d4c2..8320b51 100644 --- a/README.md +++ b/README.md @@ -273,74 +273,6 @@ await rondevu.getOfferIceCandidates( ): Promise<{ candidates: IceCandidate[], offerId: string }> ``` -### RondevuSignaler Class - -Higher-level signaling abstraction with automatic polling and event listeners. - -```typescript -import { RondevuSignaler } from '@xtr-dev/rondevu-client' - -const signaler = new RondevuSignaler( - rondevu: Rondevu, - service: string, // Service FQN without username (e.g., 'chat:1.0.0') - host?: string, // Optional: target username for answerer - pollingConfig?: { - initialInterval?: number // Default: 500ms - maxInterval?: number // Default: 5000ms - backoffMultiplier?: number // Default: 1.5 - maxRetries?: number // Default: 50 - jitter?: boolean // Default: true - } -) -``` - -#### Offerer Side - -```typescript -// Set offer (automatically starts polling for answer and ICE) -await signaler.setOffer(offer: RTCSessionDescriptionInit): Promise - -// Listen for answer -const unbind = signaler.addAnswerListener((answer) => { - console.log('Received answer:', answer) -}) - -// Listen for ICE candidates -signaler.addListener((candidate) => { - console.log('Received ICE candidate:', candidate) -}) - -// Send ICE candidate -await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise -``` - -#### Answerer Side - -```typescript -// Listen for offer (automatically searches for service) -const unbind = signaler.addOfferListener((offer) => { - console.log('Received offer:', offer) -}) - -// Set answer (automatically starts polling for ICE) -await signaler.setAnswer(answer: RTCSessionDescriptionInit): Promise - -// Send ICE candidate -await signaler.addIceCandidate(candidate: RTCIceCandidate): Promise - -// Listen for ICE candidates -signaler.addListener((candidate) => { - console.log('Received ICE candidate:', candidate) -}) -``` - -#### Cleanup - -```typescript -// Stop all polling and cleanup -signaler.dispose(): void -``` - ### RondevuAPI Class Low-level HTTP API client (used internally by Rondevu class). @@ -416,14 +348,6 @@ interface IceCandidate { candidate: RTCIceCandidateInit createdAt: number } - -interface PollingConfig { - initialInterval?: number // Default: 500ms - maxInterval?: number // Default: 5000ms - backoffMultiplier?: number // Default: 1.5 - maxRetries?: number // Default: 50 - jitter?: boolean // Default: true -} ``` ## Advanced Usage @@ -442,8 +366,10 @@ console.log(rondevu.getUsername()) // e.g., "anon-lx2w34-a3f501" // Anonymous users behave exactly like regular users await rondevu.publishService({ service: 'chat:1.0.0', - offers: [{ sdp: offerSdp }] + maxOffers: 5 }) + +await rondevu.startFilling() ``` ### Persistent Keypair @@ -510,23 +436,6 @@ const service = await rondevu.publishService({ console.log(`Published ${service.offers.length} offers`) ``` -### Custom Polling Configuration - -```typescript -const signaler = new RondevuSignaler( - rondevu, - 'chat:1.0.0', - 'alice', - { - initialInterval: 1000, // Start at 1 second - maxInterval: 10000, // Max 10 seconds - backoffMultiplier: 2, // Double each time - maxRetries: 30, // Stop after 30 retries - jitter: true // Add randomness - } -) -``` - ## Platform Support ### Modern Browsers @@ -588,14 +497,13 @@ const pc = new RTCPeerConnection(rtcConfig) const dc = pc.createDataChannel('chat') // Publish service (username auto-claimed on first publish) -const offer = await pc.createOffer() -await pc.setLocalDescription(offer) - await rondevu.publishService({ service: 'chat:1.0.0', - offers: [{ sdp: offer.sdp }] + maxOffers: 5 }) +await rondevu.startFilling() + // Browser clients can now discover and connect to chat:1.0.0@mybot ``` @@ -616,7 +524,8 @@ v0.4.0 removes high-level abstractions and uses manual WebRTC setup: **Added:** - `pollOffers()` - Combined polling for answers and ICE candidates -- `RondevuSignaler` - Simplified signaling with automatic polling +- `publishService()` - Automatic offer pool management +- `connectToService()` - Automatic answering side setup **Migration Example:** @@ -628,16 +537,13 @@ const host = new ServiceHost({ }) await host.start() -// After (v0.4.0) - Manual setup -const pc = new RTCPeerConnection() -const dc = pc.createDataChannel('chat') -const offer = await pc.createOffer() -await pc.setLocalDescription(offer) - +// After (v0.4.0+) - Automatic setup await rondevu.publishService({ - serviceFqn: 'chat:1.0.0@alice', - offers: [{ sdp: offer.sdp }] + service: 'chat:1.0.0', + maxOffers: 5 }) + +await rondevu.startFilling() ``` ## License diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 07b1540..0000000 --- a/USAGE.md +++ /dev/null @@ -1,281 +0,0 @@ -# Rondevu Client Usage Guide - -## Installation - -```bash -npm install @xtr-dev/rondevu-client -``` - -## Quick Start - -### 1. Register and Create Connection - -```typescript -import { RondevuAPI, RondevuSignaler, WebRTCRondevuConnection } from '@xtr-dev/rondevu-client'; - -const API_URL = 'https://api.ronde.vu'; - -// Register to get credentials -const api = new RondevuAPI(API_URL); -const credentials = await api.register(); - -// Create authenticated API client -const authenticatedApi = new RondevuAPI(API_URL, credentials); -``` - -### 2. Create an Offer (Offerer Side) - -```typescript -// Create a connection -const connection = new WebRTCRondevuConnection( - 'connection-id', - 'host-username', - 'service-name' -); - -// Wait for local description -await connection.ready; - -// Create offer on server -const offers = await authenticatedApi.createOffers([{ - sdp: connection.connection.localDescription!.sdp!, - ttl: 300000 // 5 minutes -}]); - -const offerId = offers[0].id; - -// Set up signaler for ICE candidate exchange -const signaler = new RondevuSignaler(authenticatedApi, offerId); -connection.setSignaler(signaler); - -// Poll for answer -const checkAnswer = setInterval(async () => { - const answer = await authenticatedApi.getAnswer(offerId); - if (answer) { - clearInterval(checkAnswer); - await connection.connection.setRemoteDescription({ - type: 'answer', - sdp: answer.sdp - }); - console.log('Connection established!'); - } -}, 1000); -``` - -### 3. Answer an Offer (Answerer Side) - -```typescript -// Get the offer -const offer = await authenticatedApi.getOffer(offerId); - -// Create connection with remote offer -const connection = new WebRTCRondevuConnection( - 'connection-id', - 'peer-username', - 'service-name', - { - type: 'offer', - sdp: offer.sdp - } -); - -// Wait for local description (answer) -await connection.ready; - -// Send answer to server -await authenticatedApi.answerOffer( - offerId, - connection.connection.localDescription!.sdp! -); - -// Set up signaler for ICE candidate exchange -const signaler = new RondevuSignaler(authenticatedApi, offerId); -connection.setSignaler(signaler); - -console.log('Connection established!'); -``` - -## Using Services - -### Publish a Service - -```typescript -import { RondevuAPI } from '@xtr-dev/rondevu-client'; - -const api = new RondevuAPI(API_URL, credentials); - -const service = await api.publishService({ - username: 'my-username', - serviceFqn: 'chat.app@1.0.0', - sdp: localDescription.sdp, - ttl: 300000, - isPublic: true, - metadata: { description: 'My chat service' }, - signature: '...', // Ed25519 signature - message: '...' // Signed message -}); - -console.log('Service UUID:', service.uuid); -``` - -### Connect to a Service - -```typescript -// Search for services -const services = await api.searchServices('username', 'chat.app@1.0.0'); - -if (services.length > 0) { - // Get service details with offer - const service = await api.getService(services[0].uuid); - - // Create connection with service offer - const connection = new WebRTCRondevuConnection( - service.serviceId, - service.username, - service.serviceFqn, - { - type: 'offer', - sdp: service.sdp - } - ); - - await connection.ready; - - // Answer the service offer - await api.answerOffer( - service.offerId, - connection.connection.localDescription!.sdp! - ); - - // Set up signaler - const signaler = new RondevuSignaler(api, service.offerId); - connection.setSignaler(signaler); -} -``` - -## Event Handling - -```typescript -import { EventBus } from '@xtr-dev/rondevu-client'; - -// Connection events -connection.events.on('state-change', (state) => { - console.log('Connection state:', state); -}); - -connection.events.on('message', (message) => { - console.log('Received message:', message); -}); - -// Custom events with EventBus -interface MyEvents { - 'user:connected': { userId: string; timestamp: number }; - 'message:sent': string; -} - -const events = new EventBus(); - -events.on('user:connected', (data) => { - console.log(`User ${data.userId} connected at ${data.timestamp}`); -}); - -events.emit('user:connected', { - userId: '123', - timestamp: Date.now() -}); -``` - -## Cleanup - -```typescript -import { createBin } from '@xtr-dev/rondevu-client'; - -const bin = createBin(); - -// Add cleanup functions -bin( - () => console.log('Cleanup 1'), - () => console.log('Cleanup 2') -); - -// Clean all -bin.clean(); -``` - -## API Reference - -### RondevuAPI - -Complete API client for Rondevu signaling server. - -**Methods:** -- `register()` - Register new peer -- `createOffers(offers)` - Create offers -- `getOffer(offerId)` - Get offer by ID -- `answerOffer(offerId, sdp)` - Answer an offer -- `getAnswer(offerId)` - Poll for answer -- `searchOffers(topic)` - Search by topic -- `addIceCandidates(offerId, candidates)` - Add ICE candidates -- `getIceCandidates(offerId, since)` - Get ICE candidates (polling) -- `publishService(service)` - Publish service -- `getService(uuid)` - Get service by UUID -- `searchServices(username, serviceFqn)` - Search services -- `checkUsername(username)` - Check availability -- `claimUsername(username, publicKey, signature, message)` - Claim username - -### RondevuSignaler - -Handles ICE candidate exchange via polling. - -**Constructor:** -```typescript -new RondevuSignaler(api: RondevuAPI, offerId: string) -``` - -**Methods:** -- `addIceCandidate(candidate)` - Send local candidate -- `addListener(callback)` - Poll for remote candidates (returns cleanup function) - -### WebRTCRondevuConnection - -WebRTC connection wrapper with type-safe events. - -**Constructor:** -```typescript -new WebRTCRondevuConnection( - id: string, - host: string, - service: string, - offer?: RTCSessionDescriptionInit -) -``` - -**Properties:** -- `id` - Connection ID -- `host` - Host username -- `service` - Service FQN -- `state` - Connection state -- `events` - EventBus for state changes and messages -- `ready` - Promise that resolves when local description is set - -**Methods:** -- `setSignaler(signaler)` - Set signaler for ICE exchange -- `queueMessage(message, options)` - Queue message for sending -- `sendMessage(message)` - Send message immediately - -### EventBus - -Type-safe event emitter with inferred types. - -**Methods:** -- `on(event, handler)` - Subscribe -- `once(event, handler)` - Subscribe once -- `off(event, handler)` - Unsubscribe -- `emit(event, data)` - Emit event -- `clear(event?)` - Clear handlers -- `listenerCount(event)` - Get listener count -- `eventNames()` - Get event names - -## Examples - -See the demo application at https://github.com/xtr-dev/rondevu-demo for a complete working example.