node-rtc-connection 1.0.19 → 2.0.4

package/README.md

@@ -1,16 +1,27 @@
-# NodeRTC
+# node-rtc-connection
 
-A Node.js WebRTC implementation with full ICE/STUN/TURN support for real peer-to-peer networking.
+[![npm version](https://img.shields.io/npm/v/node-rtc-connection.svg)](https://www.npmjs.com/package/node-rtc-connection)
+[![npm downloads](https://img.shields.io/npm/dm/node-rtc-connection.svg)](https://www.npmjs.com/package/node-rtc-connection)
+[![CI](https://github.com/nmhung1210/node-rtc-connection/actions/workflows/test.yml/badge.svg)](https://github.com/nmhung1210/node-rtc-connection/actions/workflows/test.yml)
+[![Node.js](https://img.shields.io/node/v/node-rtc-connection.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+A from-scratch, pure-Node.js WebRTC data-channel implementation that
+**interoperates with browsers**. No native dependencies — the entire ICE / DTLS
+/ SCTP stack is built on Node's `crypto` and `dgram`. Written in TypeScript;
+ships type declarations.
 
 ## Features
 
-- ✅ **Real Network Transport**: Uses actual UDP/TCP sockets for true peer-to-peer connections
-- ✅ **ICE Support**: Full Interactive Connectivity Establishment with candidate gathering
-- ✅ **STUN Support**: NAT traversal with server reflexive candidates
-- ✅ **TURN Support**: Relay candidates for restrictive network environments
-- ✅ **Data Channels**: Reliable and ordered data channels for P2P communication
-- ✅ **DTLS/SCTP**: Secure transport with DTLS encryption and SCTP for data channels
-- ✅ **Standards Compliant**: Follows WebRTC and ICE specifications
+- ✅ **Browser interoperable**: Verified end-to-end against Chromium (Playwright) and OpenSSL
+- ✅ **Real protocols, not stubs**: Genuine DTLS 1.2 handshake + SCTP association over UDP
+- ✅ **ICE** (RFC 8445): connectivity checks with MESSAGE-INTEGRITY, host/srflx/relay candidates
+- ✅ **STUN/TURN** (RFC 5389/5766): NAT traversal and relay for restrictive networks
+- ✅ **DTLS 1.2** (RFC 6347): `ECDHE_ECDSA_AES128_GCM`, mutual auth, self-signed ECDSA certs
+- ✅ **SCTP + DCEP** (RFC 8831/8832): ordered/unordered data channels, string + binary
+- ✅ **W3C API**: familiar `RTCPeerConnection` / `RTCDataChannel` surface
+- ✅ **Pure Node.js, no native deps**; CommonJS + ESM bundles with TypeScript types
 
 ## Installation
 
@@ -18,6 +29,16 @@ A Node.js WebRTC implementation with full ICE/STUN/TURN support for real peer-to
 npm install node-rtc-connection
 ```
 
+Works from both CommonJS and ES modules, and bundles TypeScript declarations:
+
+```javascript
+// CommonJS
+const { RTCPeerConnection } = require('node-rtc-connection');
+
+// ES modules / TypeScript
+import { RTCPeerConnection } from 'node-rtc-connection';
+```
+
 ## Quick Start
 
 ### Basic Local Connection (No STUN/TURN)
@@ -170,51 +191,34 @@ const config = {
 const pc = new RTCPeerConnection(config);
 ```
 
-### Query String Parameters in Server URLs
+### ICE server URLs
 
-The library supports query string parameters in ICE server URLs for advanced configuration:
+ICE server URLs are parsed with query-string support:
 
 ```javascript
 const config = {
   iceServers: [
-    // Transport selection
-    {
-      urls: 'turn:turn.example.com:3478?transport=udp',
-      username: 'user',
-      credential: 'pass'
-    },
-    
-    // Multiple parameters
-    {
-      urls: 'turn:turn.example.com:3478?transport=tcp&ttl=86400',
-      username: 'user',
-      credential: 'pass'
-    },
-    
-    // Multiple URLs with different transports
+    { urls: 'stun:stun.l.google.com:19302' },
     {
       urls: [
-        'turn:turn.cloudflare.com:3478?transport=udp',
-        'turn:turn.cloudflare.com:3478?transport=tcp',
-        'turns:turn.cloudflare.com:5349?transport=tcp'
+        'turn:turn.example.com:3478?transport=udp',
+        'turn:turn.example.com:53?transport=udp'
       ],
-      username: 'cloudflare_user',
-      credential: 'cloudflare_pass'
+      username: 'user',
+      credential: 'pass'
     }
   ]
 };
 ```
 
-**Supported Query Parameters:**
-- `transport=udp|tcp` - Select transport protocol (UDP or TCP)
-- `ttl=<seconds>` - Set allocation lifetime for TURN (default: 600)
-- Custom parameters - Can be added for vendor-specific features
+**URL format:** `stun:host[:port]` and `turn:host[:port][?transport=udp&...]`.
+The default port is `3478` (`5349` for the `turns:` scheme).
 
-**URL Format Examples:**
-- `stun:host:port` - Basic STUN server
-- `turn:host:port?transport=udp` - TURN with UDP transport
-- `turn:host:port?transport=tcp&custom=value` - Multiple parameters
-- `turns:host:port?transport=tcp` - Secure TURN over TLS
+> **Transport support:** connectivity currently uses **UDP only**. STUN
+> reflexive and TURN relay candidates are gathered over UDP; `transport=tcp`
+> and the `turns:` (TLS) scheme are parsed but not yet used for the data path,
+> so list a UDP TURN URL for the relay to work. Unknown query parameters are
+> preserved and ignored.
 
 ## Data Channel API
 
@@ -375,51 +379,29 @@ createPeerConnection().catch(console.error);
 
 ## Example Files
 
-The package includes several example files demonstrating different features:
+The package includes runnable examples in `examples/`:
 
-- **`examples/real-networking-demo.js`** - Basic peer-to-peer connection without STUN/TURN
-- **`examples/stun-demo.js`** - STUN server usage for NAT traversal
-- **`examples/turn-demo.js`** - TURN relay with full peer-to-peer communication
-- **`examples/peer-connection-demo.js`** - Simple peer connection setup
-- **`examples/simple-datachannel.js`** - Basic data channel usage
+- **`examples/node-to-node.ts`** — Two node-rtc-connection peers in one process
+  establish a real data channel and exchange string + binary messages. The
+  quickest way to see the full ICE/DTLS/SCTP stack work.
+- **`examples/browser-server.ts`** + **`examples/browser-client.html`** — A
+  Node.js HTTP server that runs a node-rtc-connection peer (the offerer) and serves a chat
+  page. A browser opens the page, runs its native `RTCPeerConnection` as the
+  answerer, and the two establish a genuine WebRTC data channel over UDP.
 
-Run examples:
+Run them (the examples are TypeScript, run via `tsx`):
 ```bash
-node examples/real-networking-demo.js
-node examples/stun-demo.js
-node examples/turn-demo.js
-```
-
-## Configuration File
+# Node ↔ Node
+npm run example:node
 
-The examples use a `peer.config.json` file for centralized configuration:
-
-```json
-{
-  "iceServers": [
-    { "urls": "stun:stun.l.google.com:19302" }
-  ],
-  "localDemo": {
-    "iceServers": []
-  },
-  "stunOnly": {
-    "iceServers": [
-      { "urls": "stun:stun.l.google.com:19302" }
-    ]
-  },
-  "turnConfig": {
-    "iceServers": [
-      { "urls": "stun:stun.example.com:3478" },
-      {
-        "urls": "turn:turn.example.com:3478",
-        "username": "user",
-        "credential": "pass"
-      }
-    ]
-  }
-}
+# Node ↔ Browser — then open http://localhost:3000
+npm run example:browser
 ```
 
+> The browser example uses plain HTTP for signaling and folds ICE candidates
+> into the SDP (non-trickle) to keep it simple. A production app would typically
+> use WebSockets with trickle ICE.
+
 ## API Reference
 
 ### RTCPeerConnection
@@ -449,7 +431,7 @@ new RTCPeerConnection(configuration?)
 ### RTCDataChannel
 
 #### Methods
-- `send(data)` - Send data (string or Buffer)
+- `send(data)` - Send `string`, `ArrayBuffer`, a typed array / `ArrayBufferView`, or a Node `Buffer`
 - `close()` - Close the channel
 
 #### Properties
@@ -462,11 +444,12 @@ new RTCPeerConnection(configuration?)
 - `id` - Channel ID
 - `readyState` - Current state ('connecting', 'open', 'closing', 'closed')
 - `bufferedAmount` - Bytes queued to send
+- `binaryType` - `'arraybuffer'` (default) or `'blob'`; controls how received binary frames are delivered
 
 ## Requirements
 
-- Node.js 14 or higher
-- UDP/TCP network access for ICE connectivity
+- Node.js 18 or higher
+- UDP network access for ICE connectivity (and to a TURN server, if used)
 
 ## Setting Up Your Own TURN Server
 
@@ -480,14 +463,40 @@ apt-get install coturn
 turnserver -v -L 0.0.0.0 -a -u user:password -r realm
 ```
 
+## Development
+
+The project is written in strict TypeScript. Sources live in `src/`; tests in
+`test/` run directly through [`tsx`](https://github.com/privatenumber/tsx) (no
+precompile step).
+
+```bash
+npm run build          # rollup → minified dist/ bundles + dist/types/ declarations
+npm run typecheck      # strict tsc --noEmit over src + tests
+npm test               # full suite (auto-starts a coturn container for the TURN test)
+npm run test:unit      # SKIP_INTEGRATION=1 — no Docker / browser / external servers
+npm run test:coverage  # full suite under c8
+```
+
+The full test suite proves interoperability against external references:
+DTLS handshakes against `openssl`, an end-to-end data channel against real
+Chromium (via Playwright), and a relay path against a real `coturn` server.
+Integration tests skip gracefully when their dependency (Docker, openssl,
+Chromium) is unavailable or when `SKIP_INTEGRATION=1`.
+
 ## License
 
-BSD-3-Clause
+MIT
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit issues or pull requests.
+Contributions are welcome! Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for
+the development workflow and conventions, and our
+[Code of Conduct](./CODE_OF_CONDUCT.md). Security issues should be reported
+privately — see [SECURITY.md](./SECURITY.md). Release notes live in
+[CHANGELOG.md](./CHANGELOG.md).
 
 ## Acknowledgments
 
-This implementation is inspired by and follows the WebRTC standards and specifications, with particular reference to Chromium's WebRTC implementation.
+This is a from-scratch, pure-Node.js implementation that follows the relevant
+IETF RFCs (8445 ICE, 6347 DTLS 1.2, 8831 SCTP-over-DTLS, 8832 DCEP) and the W3C
+WebRTC specification.