pion-node

Node.js SDK for pion-ipc — spawn and manage a Go-based WebRTC process via stdin/stdout binary IPC, exposing a W3C-style PeerConnection/DataChannel API.

Install

npm install @coclaw/pion-node

The pion-ipc Go binary is resolved in this order:

1. PION_IPC_BIN env var — explicit path to the binary
2. npm platform package — @coclaw/pion-ipc-{platform}-{arch} installed via optionalDependencies (automatic on npm install)
3. System PATH — pion-ipc found on $PATH

On supported platforms (linux-x64, linux-arm64, linux-arm, darwin-x64, darwin-arm64, win32-x64), the binary is automatically installed via npm. No manual setup needed.

Usage

import { PionIpc, RTCPeerConnection } from 'pion-node';

const ipc = new PionIpc();
await ipc.start();

const pc = new RTCPeerConnection({
  _ipc: ipc,
  iceServers: [{ urls: ['stun:stun.l.google.com:19302'] }],
});

const dc = pc.createDataChannel('chat');
dc.onopen = () => {
  dc.send('hello!');
};
dc.onmessage = (evt) => {
  console.log('received:', evt.data);
};

pc.onicecandidate = (evt) => {
  // send evt.candidate to remote peer via signaling
};

// Diagnostic: log selected candidate pair (host/srflx/relay)
pc.onselectedcandidatepairchange = () => {
  const pair = pc.selectedCandidatePair;
  console.log(`${pair.local.type} ↔ ${pair.remote.type}`);
};

const offer = await pc.createOffer();
// ... exchange SDP with remote peer ...

// Clean up
await pc.close();
await ipc.stop();

IPC Protocol

Binary framing over stdin/stdout:

[4B total_length LE] [2B header_length LE] [msgpack header] [raw payload]

Message types:

• req (request): { type, id, method, pcId?, dcLabel?, isBinary? } + payload
• res (response): { type, id, ok, error? } + payload
• evt (event): { type, event, pcId?, dcLabel?, isBinary? } + payload

Max frame size: 16 MiB.

API

PionIpc

• new PionIpc({ binPath?, logger?, timeout? }) -- create instance
• start() -- spawn process, verify with ping
• stop(timeout?) -- graceful shutdown
• request(method, opts?, payload?) -- send RPC request, returns { header, payload }
• Events: 'error', 'exit', and all Go-side events

RTCPeerConnection

• new RTCPeerConnection({ _ipc, iceServers?, settings?, _pcId? }) -- create (pcId defaults to UUID)
• createOffer() / createAnswer() -- SDP negotiation
• setRemoteDescription(desc) / setLocalDescription(desc)
• addIceCandidate(candidate)
• restartIce() -- ICE restart, returns new offer
• createDataChannel(label, opts?) -- create DataChannel (synchronous, W3C-compatible)
• getSctpStats() -- snapshot of the underlying SCTP association (see below)
• close()
• Getters: connectionState, iceConnectionState, iceGatheringState, signalingState, selectedCandidatePair
• Events: 'icecandidate', 'connectionstatechange', 'iceconnectionstatechange', 'selectedcandidatepairchange', 'icegatheringstatechange', 'signalingstatechange', 'datachannel'
• on* property handlers for all events

RTCDataChannel

• send(data) -- send string or Buffer (synchronous, W3C-compatible)
• close()
• Getters: label, ordered, readyState, bufferedAmount
• bufferedAmountLowThreshold getter/setter
• Events: 'open', 'close', 'message', 'error', 'bufferedamountlow'
• on* property handlers for all events

Note on bufferedAmount: Returns the sum of JS-side send queue size and Go-side SCTP buffer (dual-source tracking). The Go-side value is updated from each dc.send ack and refreshed on bufferedamountlow events, providing accurate flow control without manual queries.

settings — pion SettingEngine knobs

Optional per-PeerConnection configuration, forwarded to the Go side at pc.create time. Every field is independently optional; omitted fields use pion defaults. Duration fields are in milliseconds (numbers). Values above 300000 ms (5 minutes) are rejected with an error — no PeerConnection is created.

| Field | Type | Pion method | Pion default | |---|---|---|---| | sctpRtoMax | number (ms) | SetSCTPRTOMax | 60000 | | sctpMaxReceiveBufferSize | number (bytes) | SetSCTPMaxReceiveBufferSize | (pion sctp package default) | | iceDisconnectedTimeout | number (ms) | SetICETimeouts (arg 1) | 5000 | | iceFailedTimeout | number (ms) | SetICETimeouts (arg 2) | 25000 | | iceKeepAliveInterval | number (ms) | SetICETimeouts (arg 3) | 2000 | | stunGatherTimeout | number (ms) | SetSTUNGatherTimeout | 5000 | | interfaceFilter | object | SetInterfaceFilter | no filter | | ipFilter | object | SetIPFilter | no filter |

The three ICE timeout fields share a single pion setter. If the caller specifies any of them, the unspecified fields fall back to the pion defaults listed above.

interfaceFilter shape: { denyPrefixes?: string[], allowPrefixes?: string[] }. Case-sensitive HasPrefix matching on the interface name. Empty lists (or empty object) install no filter. Allow narrows the candidate set; deny wins on overlap. An empty-string entry is rejected up front (would match every interface).

ipFilter shape: { denyCIDRs?: string[], allowCIDRs?: string[] }. CIDRs accept IPv4 and IPv6 (net.ParseCIDR semantics); invalid strings fail pc.create. Same allow / deny semantics as interfaceFilter.

const pc = new RTCPeerConnection({
  _ipc: ipc,
  iceServers: [{ urls: ['stun:stun.l.google.com:19302'] }],
  settings: {
    sctpRtoMax: 10000,   // shorten worst-case SCTP backoff after long idle
    iceFailedTimeout: 15000,
    interfaceFilter: { denyPrefixes: ['docker', 'br-', 'veth'] },
    ipFilter: { denyCIDRs: ['172.16.0.0/12'] },
  },
});

getSctpStats() — SCTP association snapshot

Returns a snapshot of the underlying SCTP association. Useful for diagnosing stalls after long idle periods — correlating congestionWindow and bytesSent deltas over time reveals whether the sender is stuck in loss recovery (cwnd collapsed back to ~1 MTU with bytesSent flat across samples).

Return values:

• An object with the fields below, once the SCTP association is up.
• null when the association has not yet been established (before DTLS handshake completes).
• After close() the call rejects with the underlying IPC error — the PeerConnection no longer exists on the Go side.

| Field | Type | Unit | Description | |---|---|---|---| | bytesSent | number | bytes | Cumulative bytes sent on the SCTP association | | bytesReceived | number | bytes | Cumulative bytes received on the SCTP association | | srttMs | number | ms | Smoothed round-trip time; 0 before first RTT measurement | | congestionWindow | number | bytes | Current congestion window (cwnd) | | receiverWindow | number | bytes | Peer's receiver window (rwnd) | | mtu | number | bytes | Current MTU |

const stats = await pc.getSctpStats();
if (stats === null) {
  console.log('SCTP association not yet established');
} else {
  console.log(`cwnd=${stats.congestionWindow} srtt=${stats.srttMs}ms sent=${stats.bytesSent}`);
}

Not exposed (no public pion API in v1.8.36): current RTO value, t3RTX backoff level (nRtos), inflight chunk count. These would require upstream pion changes.

Do not call at high frequency. The call internally walks the PeerConnection's transceivers, candidates, and data channels. A 5-10 s sampling cadence is fine; tighter than 1 s across many PeerConnections is wasteful.

License

Apache-2.0