@xtr-dev/rondevu-server 0.2.4 → 0.4.0

package/README.md

@@ -30,11 +30,11 @@ Username Claiming → Service Publishing → Service Discovery → WebRTC Connec
 
 alice claims "alice" with Ed25519 signature
   ↓
-alice publishes com.example.chat@1.0.0 → receives UUID abc123
+alice publishes com.example.chat@1.0.0 with multiple offers → receives UUID abc123
   ↓
-bob queries alice's services → gets UUID abc123
+bob requests alice/com.example.chat@1.0.0 → gets compatible service with available offer
   ↓
-bob connects to UUID abc123 → WebRTC connection established
+WebRTC connection established via offer/answer exchange
 ```
 
 ## Quick Start
@@ -77,15 +77,28 @@ Generates a cryptographically random 128-bit peer ID.
 }
 ```
 
-### Username Management
+### User Management (RESTful)
 
-#### `POST /usernames/claim`
+#### `GET /users/:username`
+Check username availability and claim status
+
+**Response:**
+```json
+{
+  "username": "alice",
+  "available": false,
+  "claimedAt": 1733404800000,
+  "expiresAt": 1765027200000,
+  "publicKey": "..."
+}
+```
+
+#### `POST /users/:username`
 Claim a username with cryptographic proof
 
 **Request:**
 ```json
 {
-  "username": "alice",
   "publicKey": "base64-encoded-ed25519-public-key",
   "signature": "base64-encoded-signature",
   "message": "claim:alice:1733404800000"
@@ -107,46 +120,37 @@ Claim a username with cryptographic proof
 - Timestamp must be within 5 minutes (replay protection)
 - Expires after 365 days, auto-renewed on use
 
-#### `GET /usernames/:username`
-Check username availability and claim status
-
-**Response:**
-```json
-{
-  "username": "alice",
-  "available": false,
-  "claimedAt": 1733404800000,
-  "expiresAt": 1765027200000,
-  "publicKey": "..."
-}
-```
+#### `GET /users/:username/services/:fqn`
+Get service by username and FQN with semver-compatible matching
 
-#### `GET /usernames/:username/services`
-List all services for a username (privacy-preserving)
+**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:**
 ```json
 {
+  "uuid": "abc123",
+  "serviceId": "service-id",
   "username": "alice",
-  "services": [
-    {
-      "uuid": "abc123",
-      "isPublic": false
-    },
-    {
-      "uuid": "def456",
-      "isPublic": true,
-      "serviceFqn": "com.example.public@1.0.0",
-      "metadata": { "description": "Public service" }
-    }
-  ]
+  "serviceFqn": "chat.app@1.0.0",
+  "offerId": "offer-hash",
+  "sdp": "v=0...",
+  "isPublic": true,
+  "metadata": {},
+  "createdAt": 1733404800000,
+  "expiresAt": 1733405100000
 }
 ```
 
-### Service Management
+**Note:** Returns a single available offer from the service. If all offers are in use, returns 503.
+
+### Service Management (RESTful)
 
-#### `POST /services`
-Publish a service (requires authentication and username signature)
+#### `POST /users/:username/services`
+Publish a service with multiple offers (requires authentication and username signature)
 
 **Headers:**
 - `Authorization: Bearer {peerId}:{secret}`
@@ -154,9 +158,11 @@ Publish a service (requires authentication and username signature)
 **Request:**
 ```json
 {
-  "username": "alice",
   "serviceFqn": "com.example.chat@1.0.0",
-  "sdp": "v=0...",
+  "offers": [
+    { "sdp": "v=0..." },
+    { "sdp": "v=0..." }
+  ],
   "ttl": 300000,
   "isPublic": false,
   "metadata": { "description": "Chat service" },
@@ -165,12 +171,30 @@ Publish a service (requires authentication and username signature)
 }
 ```
 
-**Response:**
+**Response (Full service details):**
 ```json
 {
-  "serviceId": "uuid-v4",
   "uuid": "uuid-v4-for-index",
-  "offerId": "offer-hash-id",
+  "serviceId": "uuid-v4",
+  "username": "alice",
+  "serviceFqn": "com.example.chat@1.0.0",
+  "offers": [
+    {
+      "offerId": "offer-hash-1",
+      "sdp": "v=0...",
+      "createdAt": 1733404800000,
+      "expiresAt": 1733405100000
+    },
+    {
+      "offerId": "offer-hash-2",
+      "sdp": "v=0...",
+      "createdAt": 1733404800000,
+      "expiresAt": 1733405100000
+    }
+  ],
+  "isPublic": false,
+  "metadata": { "description": "Chat service" },
+  "createdAt": 1733404800000,
   "expiresAt": 1733405100000
 }
 ```
@@ -203,7 +227,7 @@ Get service details by UUID
 }
 ```
 
-#### `DELETE /services/:serviceId`
+#### `DELETE /users/:username/services/:fqn`
 Unpublish a service (requires authentication and ownership)
 
 **Headers:**
@@ -216,80 +240,91 @@ Unpublish a service (requires authentication and ownership)
 }
 ```
 
-### Service Discovery
+### WebRTC Signaling (Service-Based)
 
-#### `POST /index/:username/query`
-Query a service by FQN
+#### `POST /services/:uuid/answer`
+Answer a service offer (requires authentication)
+
+**Headers:**
+- `Authorization: Bearer {peerId}:{secret}`
 
 **Request:**
 ```json
 {
-  "serviceFqn": "com.example.chat@1.0.0"
+  "sdp": "v=0..."
 }
 ```
 
 **Response:**
 ```json
 {
-  "uuid": "abc123",
-  "allowed": true
+  "success": true,
+  "offerId": "offer-hash"
 }
 ```
 
-### Offer Management (Low-level)
-
-#### `POST /offers`
-Create one or more offers (requires authentication)
+#### `GET /services/:uuid/answer`
+Get answer for a service (offerer polls this)
 
 **Headers:**
 - `Authorization: Bearer {peerId}:{secret}`
 
-**Request:**
+**Response:**
 ```json
 {
-  "offers": [
-    {
-      "sdp": "v=0...",
-      "ttl": 300000
-    }
-  ]
+  "offerId": "offer-hash",
+  "answererId": "answerer-peer-id",
+  "sdp": "v=0...",
+  "answeredAt": 1733404800000
 }
 ```
 
-#### `GET /offers/mine`
-List all offers owned by authenticated peer
+**Note:** Returns 404 if not yet answered
 
-#### `PUT /offers/:offerId/heartbeat`
-Update last_seen timestamp for an offer
+#### `POST /services/:uuid/ice-candidates`
+Post ICE candidates for a service (requires authentication)
 
-#### `DELETE /offers/:offerId`
-Delete a specific offer
-
-#### `POST /offers/:offerId/answer`
-Answer an offer (locks it to answerer)
+**Headers:**
+- `Authorization: Bearer {peerId}:{secret}`
 
 **Request:**
 ```json
 {
-  "sdp": "v=0..."
+  "candidates": ["candidate:1 1 UDP..."],
+  "offerId": "optional-offer-id"
 }
 ```
 
-#### `GET /offers/answers`
-Poll for answers to your offers
+**Response:**
+```json
+{
+  "count": 1,
+  "offerId": "offer-hash"
+}
+```
 
-#### `POST /offers/:offerId/ice-candidates`
-Post ICE candidates for an offer
+**Note:** If `offerId` is omitted, the server will auto-detect the peer's offer
 
-**Request:**
+#### `GET /services/:uuid/ice-candidates?since=1234567890&offerId=optional-offer-id`
+Get ICE candidates from the other peer (requires authentication)
+
+**Headers:**
+- `Authorization: Bearer {peerId}:{secret}`
+
+**Response:**
 ```json
 {
-  "candidates": ["candidate:1 1 UDP..."]
+  "candidates": [
+    {
+      "candidate": "candidate:1 1 UDP...",
+      "createdAt": 1733404800000
+    }
+  ],
+  "offerId": "offer-hash"
 }
 ```
 
-#### `GET /offers/:offerId/ice-candidates?since=1234567890`
-Get ICE candidates from the other peer
+**Note:** Returns candidates from the opposite role (offerer gets answerer candidates and vice versa)
 
 ## Configuration
 
@@ -321,11 +356,19 @@ Environment variables:
 - `id` (PK): Service ID (UUID)
 - `username` (FK): Owner username
 - `service_fqn`: Fully qualified name (com.example.chat@1.0.0)
-- `offer_id` (FK): WebRTC offer ID
 - `is_public`: Public/private flag
 - `metadata`: JSON metadata
 - `created_at`, `expires_at`: Timestamps
 
+### offers
+- `id` (PK): Offer ID (hash of SDP)
+- `peer_id` (FK): Owner peer ID
+- `service_id` (FK): Optional link to service (null for standalone offers)
+- `sdp`: WebRTC offer SDP
+- `answerer_peer_id`: Peer ID of answerer (null until answered)
+- `answer_sdp`: WebRTC answer SDP (null until answered)
+- `created_at`, `expires_at`, `last_seen`: Timestamps
+
 ### service_index (privacy layer)
 - `uuid` (PK): Random UUID for discovery
 - `service_id` (FK): Links to service