Add forceRelay option to Peer API and document raw peerconnection property (#3313)

* add forceRelay options

* document peerconnection

src/docs/src/Peer/connect.md

@@ -31,6 +31,7 @@ A string invite code created by `puter.peer.serve()`.
 `options` is an object with the following properties:
 
 - `iceServers` (`RTCIceServer[]`) Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays.
+- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges may apply.
 
 ## Return value
 
@@ -41,6 +42,7 @@ A `Promise` that resolves to a `PuterPeerConnection` instance.
 - `send(data)` - Send a message to the peer. Supports strings, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
 - `close(reason)` - Close the connection.
 - `owner` (`object`) - Information about the user who created the server.
+- `peerconnection` (`RTCPeerConnection`) - the raw underlying RTC handle for this connection.
 - `open` event: Fired when the data channel is ready.
 - `message` event: Fired when a message is received (`event.data`).
 - `close` event: Fired when the connection closes (`event.reason`).

src/docs/src/Peer/serve.md

@@ -27,6 +27,7 @@ const server = await puter.peer.serve(options);
 `options` is an object with the following properties:
 
 - `iceServers` (`RTCIceServer[]`) Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays.
+- `forceRelay` (`boolean`) Whether to force connections to route through a relay instead of attempting peer-to-peer (default). Metering charges will increase.
 
 ## Return value
 

src/puter-js/src/modules/Peer.js

@@ -189,6 +189,7 @@ class PuterPeerConnection extends EventTarget {
         super();
         this.#peerConfig = peerConfig;
         this.peerconnection = new RTCPeerConnection({
+            iceTransportPolicy: peerConfig.forceRelay ? "relay" : "all",
             iceServers: peerConfig.iceServers,
         });
         this.#datachannel = this.peerconnection.createDataChannel('channel-1', { negotiated: true, id: 2 });
@@ -446,6 +447,7 @@ class Peer {
             authToken: this.authToken,
             iceServers,
             signallerUrl: this.#signallerUrl,
+            forceRelay: options?.forceRelay
         };
     }
     async serve (options) {

src/puter-js/types/modules/peer.d.ts

@@ -2,6 +2,7 @@
 export interface PuterPeerOptions {
     /** Custom ICE servers (STUN/TURN) to use instead of the Puter-managed relays. */
     iceServers?: RTCIceServer[];
+    forceRelay?: boolean;
 }
 
 /** Metadata about a peer user. */