@yz-social/webrtc 0.0.1

package/index.js

@@ -0,0 +1,3 @@
+export { WebRTC } from './lib/webrtc.js';
+export { PromiseWebRTC } from './lib/promisewebrtc.js';
+export { TrickleWebRTC } from './lib/tricklewebrtc.js';

package/lib/datachannels.js

@@ -0,0 +1,147 @@
+import { WebRTCPeerEvents } from './peerevents.js';
+
+// Data Channels:
+// - 
+// - Send/receive, including the break-up of long messages and re-assembly.
+
+export class WebRTCDataChannels extends WebRTCPeerEvents {
+
+  // Negotiated channels use specific integers on both sides, starting with this number.
+  // We do not start at zero because the non-negotiated channels (as used on server relays) generate their
+  // own ids starting with 0, and we don't want to conflict.
+  // The spec says these can go to 65,534, but I find that starting greater than the value here gives errors.
+  // As of 7/6/25, current evergreen browsers work with 1000 base, but Firefox fails in our case (10 negotatiated channels)
+  // if any ids are 256 or higher.
+  static BASE_CHANNEL_ID = 125;
+  channelId = this.constructor.BASE_CHANNEL_ID;
+  get hasStartedConnecting() {
+    return this.channelId > this.constructor.BASE_CHANNEL_ID;
+  }
+  close(removeConnection = true) {
+    this.channelId = this.constructor.BASE_CHANNEL_ID;
+    super.close();
+    if (removeConnection) this.constructor.connections.delete(this.serviceLabel);
+  }
+  async ensureDataChannel(channelName, channelOptions = {}, signals = null) { // Return a promise for an open data channel on this connection.
+    // Much of this machinery is for ealing with the first data channel on either side in the case that the connection as a whole
+    // has not yet been made. 
+
+    const hasStartedConnecting = this.hasStartedConnecting; // True for first channel only. Must ask before incrementing id.
+    const id = this.channelId++; // This and everything leading up to it must be synchronous on this instance, so that id assignment is deterministic.
+    const negotiated = this.multiplex && hasStartedConnecting;
+    const allowOtherSideToCreate = !hasStartedConnecting /*!negotiated*/ && !!signals; // Only the 0th with signals waits passively.
+    // signals can be nullish, in which case the real signals will have to be assigned later. This allows the data channel to be started (and to consume
+    // a channelId) synchronously, but the promise won't resolve until the real signals are supplied later. This is
+    // useful in multiplexing an ordered series of data channels on an ANSWER connection, where the data channels must
+    // match up with an OFFER connection on a peer. This works because of the wonderful happenstance that answer connections
+    // getDataChannelPromise (which doesn't require the connection to yet be open) rather than createDataChannel (which would
+    // require the connection to already be open).
+    const useSignals = !hasStartedConnecting && signals?.length;
+    const options = negotiated ? {id, negotiated, ...channelOptions} : channelOptions;
+    this.log({label: this.label, channelName, multiplex: this.multiplex, hasStartedConnecting, id, negotiated, allowOtherSideToCreate, useSignals, options});
+    if (hasStartedConnecting) {
+      await this.connected; // Before creating promise.
+      // I sometimes encounter a bug in Safari in which ONE of the channels created soon after connection gets stuck in
+      // the connecting readyState and never opens. Experimentally, this seems to be robust.
+      //
+      // Note to self: If it should turn out that we still have problems, try serializing the calls to peer.createDataChannel
+      // so that there isn't more than one channel opening at a time.
+      await new Promise(resolve => setTimeout(resolve, 100));
+    } else if (useSignals) {
+      this.signals = signals;
+    }
+    const promise = allowOtherSideToCreate ?
+	  this.getDataChannelPromise(channelName) :
+	  this.createDataChannel(channelName, options);
+    return await promise;
+  }
+
+  createDataChannel(label = "data", channelOptions = {}) { // Promise resolves when the channel is open (which will be after any needed negotiation).
+    return new Promise(resolve => {
+      this.log('create data-channel', label, channelOptions);
+      let channel = this.peer.createDataChannel(label, channelOptions);
+      this.noteChannel(channel, 'explicit'); // Noted even before opened.
+      // The channel may have already been opened on the other side. In this case, all browsers fire the open event anyway,
+      // but wrtc (i.e., on nodeJS) does not. So we have to explicitly check.
+      switch (channel.readyState) {
+      case 'open':
+	setTimeout(() => resolve(channel), 10);
+	break;
+      case 'connecting':
+	channel.onopen = _ => resolve(channel);
+	break;
+      default:
+	throw new Error(`Unexpected readyState ${channel.readyState} for data channel ${label}.`);
+      }
+    });
+  }
+  waitingChannels = {}; // channelName => resolvers
+  getDataChannelPromise(label = "data") { // Resolves to an open data channel.
+    return new Promise(resolve => {
+      this.log('promise data-channel', label);
+      this.waitingChannels[label] = resolve;
+    });
+  }
+  resetPeer() { // Reset a 'connected' property that promised to resolve when opened, and track incoming datachannels.
+    super.resetPeer();
+    this.connected = new Promise(resolve => { // this.connected is a promise that resolves when we are.
+      this.peer.addEventListener('connectionstatechange', event => {
+	if (this.peer.connectionState === 'connected') {
+	  resolve(true);
+	}
+      });
+    });
+    this.peer.addEventListener('datachannel', event => { // Resolve promise made with getDataChannelPromise().
+      const channel = event.channel;
+      const label = channel.label;
+      const waiting = this.waitingChannels[label];
+      this.noteChannel(channel, 'datachannel event', waiting); // Regardless of whether we are waiting.
+      if (!waiting) return; // Might not be explicitly waiting. E.g., routers.
+      delete this.waitingChannels[label];
+      waiting(channel);
+    });
+  }
+  
+  // TODO: (Optionaly?) Set up generic jsonrpc on each channel, along with serialization and fragmentation/assembly for long messages. (See collections/serializer)
+
+  
+  // We need to know if there are open data channels. There is a proposal and even an accepted PR for RTCPeerConnection.getDataChannels(),
+  // https://github.com/w3c/webrtc-extensions/issues/110
+  // but it hasn't been deployed everywhere yet. So we'll need to keep our own count.
+  // Alas, a count isn't enough, because we can open stuff, and the other side can open stuff, but if it happens to be
+  // the same "negotiated" id, it isn't really a different channel. (https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/datachannel_event
+  dataChannels = new Map(); // channelName => Open channel objects.
+  reportChannels() { // Return a report string useful for debugging.
+    const entries = Array.from(this.dataChannels.entries());
+    const kv = entries.map(([k, v]) => `${k}:${v.id}`);
+    return `${this.dataChannels.size}/${kv.join(', ')}`;
+  }
+  noteChannel(channel, source, waiting) { // Bookkeep open channel and return it.
+    // Emperically, with multiplex false: //   18 occurrences, with id=null|0|1 as for eventchannel or createDataChannel
+    //   Apparently, without negotiation, id is initially null (regardless of options.id), and then assigned to a free value during opening
+    const key = channel.label; //fixme channel.id === null ? 1 : channel.id;
+    const existing = this.dataChannels.get(key);
+    this.log('got data-channel', source, key, channel.readyState, 'existing:', existing, 'waiting:', waiting);
+    this.dataChannels.set(key, channel);
+    channel.addEventListener('close', event => { // Close whole connection when no more data channels or streams.
+      this.dataChannels.delete(key);
+      // If there's nothing open, close the connection.
+      if (this.dataChannels.size) return;
+      if (this.peer.getSenders().length) return;
+      this.close();
+    });
+    return channel;
+  }
+  close() {
+    super.close();
+    // If the webrtc implementation closes the data channels before the peer itself, then this.dataChannels will be empty.
+    // But if not (e.g., status 'failed' or 'disconnected' on Safari), then let us explicitly close them so that Synchronizers know to clean up.
+    for (const channel of this.dataChannels.values()) {
+      if (channel.readyState !== 'open') continue; // Keep debugging sanity.
+      // It appears that in Safari (18.5) for a call to channel.close() with the connection already internally closed, Safari
+      // will set channel.readyState to 'closing', but NOT fire the closed or closing event. So we have to dispatch it ourselves.
+      //channel.close();
+      channel.dispatchEvent(new Event('close'));
+    }
+  }
+}

package/lib/peerevents.js

@@ -0,0 +1,56 @@
+import { WebRTCUtilities } from './utilities.js';
+
+// Extendible methods for events on the RTCPeerConnection.
+export class WebRTCPeerEvents extends WebRTCUtilities {
+  resetPeer() {
+    const peer = super.resetPeer();
+
+    peer.onnegotiationneeded = event => this.negotiationneeded(event);
+    peer.onicecandidate = event => this.onLocalIceCandidate(event);
+    // I don't think anyone actually signals this. Instead, they reject from addIceCandidate, which we handle the same.
+    peer.onicecandidateerror = error => this.icecandidateError(error);
+    // I think this is redundant because no implementation fires this event any significant time ahead of emitting icecandidate with an empty event.candidate.
+    peer.onicegatheringstatechange = event => (peer.iceGatheringState === 'complete') && this.onLocalEndIce;
+    peer.onconnectionstatechange = event => this.connectionStateChange(this.peer.connectionState);
+
+    return peer;
+  }
+  negotiationneeded() { // Something has changed locally (new stream, or network change), such that we have to start negotiation.
+    this.log('negotiationnneeded');
+    this.peer.createOffer()
+      .then(offer => {
+        this.peer.setLocalDescription(offer); // promise does not resolve to offer
+	return offer;
+      })
+      .then(offer => this.signal('offer', offer))
+      .catch(error => this.negotiationneededError(error));
+  }
+  negotiationneededError(eventOrException) {
+    this.logError('negotiationneeded', eventOrException);
+  }
+  icecandidateError(eventOrException) { // For errors on this peer during gathering.
+    // Can be overridden or extended by applications.
+
+    // STUN errors are in the range 300-699. See RFC 5389, section 15.6
+    // for a list of codes. TURN adds a few more error codes; see
+    // RFC 5766, section 15 for details.
+    // Server could not be reached are in the range 700-799.
+    const code = eventOrException.code || eventOrException.errorCode || eventOrException.status;
+    // Chrome gives 701 errors for some turn servers that it does not give for other turn servers.
+    // This isn't good, but it's way too noisy to slog through such errors, and I don't know how to fix our turn configuration.
+    if (code === 701) return;
+    this.logError('ice', eventOrException);
+  }
+  onLocalIceCandidate(event) {
+    // The spec says that a null candidate should not be sent, but that an empty string candidate should. Safari (used to?) get errors either way.
+    if (!event.candidate || !event.candidate.candidate) this.onLocalEndIce();
+    else this.signal('icecandidate', event.candidate);
+  }
+  onLocalEndIce() { // Triggered on our side by any/all of onicecandidate with no event.candidate, iceGatheringState === 'complete'.
+    // I.e., can happen multiple times. Subclasses might do something.
+  }
+  connectionStateChange(state) {
+    this.log('state change:', state);
+    if (['disconnected', 'failed', 'closed'].includes(state)) this.close(); // Other behavior are reasonable, tolo.
+  }
+}

package/lib/promisewebrtc.js

@@ -0,0 +1,58 @@
+import { WebRTC } from './webrtc.js';
+
+export class PromiseWebRTC extends WebRTC {
+  // Extends WebRTC.signal() such that:
+  // - instance.signals answers a promise that will resolve with an array of signal messages.
+  // - instance.signals = [...signalMessages] will dispatch those messages.
+  //
+  // For example, suppose peer1 and peer2 are instances of this.
+  // 0. Something triggers negotiation on peer1 (such as calling peer1.createDataChannel()). 
+  // 1. peer1.signals resolves with <signal1>, a POJO to be conveyed to peer2.
+  // 2. Set peer2.signals = <signal1>.
+  // 3. peer2.signals resolves with <signal2>, a POJO to be conveyed to peer1.
+  // 4. Set peer1.signals = <signal2>.
+  // 5. Data flows, but each side whould grab a new signals promise and be prepared to act if it resolves.
+  //
+  constructor({iceTimeout = 2e3, ...properties}) {
+    super(properties);
+    this.iceTimeout = iceTimeout;
+  }
+  get signals() { // Returns a promise that resolve to the signal messaging when ice candidate gathering is complete.
+    return this._signalPromise ||= new Promise((resolve, reject) => this._signalReady = {resolve, reject});
+  }
+  set signals(data) { // Set with the signals received from the other end.
+    data.forEach(([type, message]) => this[type](message));
+  }
+  onLocalIceCandidate(event) {
+    // Each wrtc implementation has its own ideas as to what ice candidates to try before emitting them in icecanddiate.
+    // Most will try things that cannot be reached, and give up when they hit the OS network timeout. Forty seconds is a long time to wait.
+    // If the wrtc is still waiting after our iceTimeout (2 seconds), lets just go with what we have.
+    this.timer ||= setTimeout(() => this.onLocalEndIce(), this.iceTimeout);
+    super.onLocalIceCandidate(event);
+  }
+  clearIceTimer() {
+    clearTimeout(this.timer);
+    this.timer = null;
+  }
+  async onLocalEndIce() { // Resolve the promise with what we've been gathering.
+    this.clearIceTimer();
+    if (!this._signalPromise) {
+      //this.logError('ice', "End of ICE without anything waiting on signals."); // Not helpful when there are three ways to receive this message.
+      return;
+    }
+    this._signalReady.resolve(this.sending);
+    this.sending = [];
+  }
+  sending = [];
+  signal(type, message) {
+    super.signal(type, message);
+    this.sending.push([type, message]);
+  }
+  close() {
+    if (this.peer.connectionState === 'failed') this._signalPromise?.reject?.();
+    super.close();
+    this.clearIceTimer();
+    this._signalPromise = this._signalReady = null;
+    this.sending = [];
+  }
+}

package/lib/tricklewebrtc.js

@@ -0,0 +1,49 @@
+import { WebRTC } from './webrtc.js';
+
+export class TrickleWebRTC extends WebRTC {
+  // Same idea as PromiseWebRTC, but instead of waiting for End of Ice (or timeout), signals will resolve as soon as there
+  // are any signals ready to be picked up, and a new call to get signals will start collecting a new set of promises.
+  // Signals stops collecting new signals when we connect (even if there are more ice candidates, and even if signals is
+  // an empty array at that point).
+
+  get signals() { // Returns a promise that collects signals until the next time someone calls this.signals,
+    // but which resolves as soon as it is not empty (and continues to accumulate).
+    // Clients must be careful to no grab a new signals promise until the previous one has resolved.
+    const { xx = 0, sending } = this;
+    const { promise, resolve } = Promise.withResolvers();
+    const counter = xx;
+    Object.assign(promise, {resolve, counter});
+    this._signalPromise = promise;
+    this.sending = [];
+    this.xx = counter + 1;
+    //console.log(this.label, 'get signals', {xx, sending, promise, counter, promise, sending: this.sending});
+    return promise;
+  }
+  set signals(data) { // Set with the signals received from the other end.
+    data.forEach(([type, message]) => this[type](message));
+  }
+  // onLocalEndIce() {
+  //   console.log(this.label, 'end ice');
+  //   this.signal('icecandidate', null); // So that clients can recognize that they should not await more signals.
+  // }
+  // connectionStateChange(state) {
+  //   //console.log(this.label, 'connection state', state);    
+  //   super.connectionStateChange(state);
+  //   //this._signalPromise.resolve(this.sending);
+  // }
+  sending = [];
+  signal(type, message) {
+    super.signal(type, message);
+    this.sending.push([type, message]);
+    // Until another call to get signals (which replaces _signalPromise), we will continue to accumulate into
+    // the same sending array, and subsequent signals will re-resolve (which has no effect on the promise).
+    this._signalPromise.resolve(this.sending);
+    //console.log(this.label, 'signal', type, 'resolving', this._signalPromise);
+  }
+  // close() {
+  //   if (this.peer.connectionState === 'failed') this._signalPromise?.reject?.();
+  //   super.close();
+  //   // this._signalPromise = null;
+  //   // this.sending = [];
+  // }
+}

package/lib/utilities.js

@@ -0,0 +1,92 @@
+import wrtc from '#wrtc';
+
+const iceServers = [ // Some default stun and even turn servers.
+  
+  { urls: 'stun:stun.l.google.com:19302'},
+  // https://freestun.net/  Currently 50 KBit/s. (2.5 MBit/s fors $9/month)
+  { urls: 'stun:freestun.net:3478' },
+
+  //{ urls: 'turn:freestun.net:3478', username: 'free', credential: 'free' },
+  // Presumably traffic limited. Can generate new credentials at https://speed.cloudflare.com/turn-creds
+  // Also https://developers.cloudflare.com/calls/ 1 TB/month, and $0.05 /GB after that.
+  { urls: 'turn:turn.speed.cloudflare.com:50000', username: '826226244cd6e5edb3f55749b796235f420fe5ee78895e0dd7d2baa45e1f7a8f49e9239e78691ab38b72ce016471f7746f5277dcef84ad79fc60f8020b132c73', credential: 'aba9b169546eb6dcc7bfb1cdf34544cf95b5161d602e3b5fa7c8342b2e9802fb' }
+
+  // See also:
+  // https://fastturn.net/ Currently 500MB/month? (25 GB/month for $9/month)
+  // https://xirsys.com/pricing/ 500 MB/month (50 GB/month for $33/month)
+  // Also https://www.npmjs.com/package/node-turn or https://meetrix.io/blog/webrtc/coturn/installation.html
+];
+
+// Basic logging and configuration wrapper around an instance of RTCPeerConnection.
+export class WebRTCUtilities {
+  constructor({label = '', configuration = null, debug = false, error = console.error, ...rest} = {}) {
+    configuration ??= {iceServers}; // If configuration can be ommitted or explicitly as null, to use our default. But if {}, leave it be.
+    Object.assign(this, {label, configuration, debug, error, ...rest});
+    this.resetPeer();
+    this.connectionStartTime = Date.now();
+  }
+  signal(type, message) { // Subclasses must override or extend. Default just logs.
+    this.log('sending', type, type.length, JSON.stringify(message).length);
+  }
+  close() {
+    if ((this.peer.connectionState === 'new') && (this.peer.signalingState === 'stable')) return;
+    this.resetPeer();
+  }
+  instanceVersion = 0;
+  resetPeer() { // Set up a new RTCPeerConnection.
+    const old = this.peer;
+    if (old) {
+      old.onnegotiationneeded = old.onicecandidate = old.onicecandidateerror = old.onconnectionstatechange = null;
+      // Don't close unless it's been opened, because there are likely handlers that we don't want to fire.
+      if (old.connectionState !== 'new') old.close();
+    }
+    const peer = this.peer = new wrtc.RTCPeerConnection(this.configuration);
+    peer.instanceVersion = this.instanceVersion++;
+
+    return peer;
+  }
+  async reportConnection(doLogging = false) { // Update self with latest wrtc stats (and log them if doLogging true). See Object.assign for properties.
+    const stats = await this.peer.getStats();
+    let transport;
+    for (const report of stats.values()) {
+      if (report.type === 'transport') {
+	transport = report;
+	break;
+      }
+    }
+    let candidatePair = transport && stats.get(transport.selectedCandidatePairId);
+    if (!candidatePair) { // Safari doesn't follow the standard.
+      for (const report of stats.values()) {
+	if ((report.type === 'candidate-pair') && report.selected) {
+	  candidatePair = report;
+	  break;
+	}
+      }
+    }
+    if (!candidatePair) {
+      console.warn(this.label, 'got stats without candidatePair', Array.from(stats.values()));
+      return;
+    }
+    const remote = stats.get(candidatePair.remoteCandidateId);
+    const {protocol, candidateType} = remote;
+    const now = Date.now();
+    Object.assign(this, {stats, transport, candidatePair, remote, protocol, candidateType, statsTime: now});
+    if (doLogging) console.info(this.label, 'connected', protocol, candidateType, ((now - this.connectionStartTime)/1e3).toFixed(1));
+  }
+  log(...rest) { // console.log(...rest) ONLY if debug is set.
+    if (this.debug) console.log(this.label, this.peer.instanceVersion, ...rest);
+  }
+  logError(label, eventOrException) { // Call error with the gathered platform-specific data. Returns the gatheredata.
+    const data = [this.label, this.peer.instanceVersion, ...this.constructor.gatherErrorData(label, eventOrException)];
+    this.error(...data);
+    return data;
+  }
+  static gatherErrorData(label, eventOrException) { // Normalize several context- or platform-specific properties.
+    return [
+      label + " error:",
+      eventOrException.code || eventOrException.errorCode || eventOrException.status || "", // First is deprecated, but still useful.
+      eventOrException.url || eventOrException.name || '',
+      eventOrException.message || eventOrException.errorText || eventOrException.statusText || eventOrException
+    ];
+  }
+}

package/lib/webrtc.js

@@ -0,0 +1,42 @@
+import { WebRTCDataChannels } from './datachannels.js';
+
+// Basics.
+export class WebRTC extends WebRTCDataChannels {
+  static connections = new Map();
+  static ensure({serviceLabel, multiplex = true, ...rest}) { // Answer the named connection, creating it if there isn't already a CONNECTED one by this name.
+    // The serviceLabel is used as the log label throughout.
+    // E.g., if a node has connections to many other nodes, but with multiple channels on each connection, then it is
+    // convenient to name the shared connection with the id of the other side.
+    //
+    // If running both ends in the same Javascript, be sure to give them different names!
+
+    let connection = this.connections.get(serviceLabel);
+    // It is possible that we were backgrounded before we had a chance to act on a closing connection and remove it.
+    if (connection) {
+      const {connectionState, signalingState} = connection.peer;
+      if ((connectionState === 'new') || (connectionState === 'closed') || (signalingState === 'closed')) connection = null;
+    }
+    if (!connection) {
+      connection = new this({label: serviceLabel, multiplex, ...rest});
+      if (multiplex) this.connections.set(serviceLabel, connection);
+    }
+    return connection;
+  }
+
+  // Handlers for signal messages from the peer.
+  // Note that one peer will receive offer(), and the other will receive answer(). Both receive icecandidate.
+  offer(offer) { // Handler for receiving an offer from the other user (who started the signaling process).
+    // Note that during signaling, we will receive negotiationneeded/answer, or offer, but not both, depending
+    // on whether we were the one that started the signaling process.
+    this.peer.setRemoteDescription(offer)
+      .then(_ => this.peer.createAnswer())
+      .then(answer => this.peer.setLocalDescription(answer)) // promise does not resolve to answer
+      .then(_ => this.signal('answer', this.peer.localDescription));
+  }
+  answer(answer) { // Handler for finishing the signaling process that we started.
+    this.peer.setRemoteDescription(answer);
+  }
+  icecandidate(iceCandidate) { // Handler for a new candidate received from the other end through signaling.
+    this.peer.addIceCandidate(iceCandidate).catch(error => this.icecandidateError(error));
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@yz-social/webrtc",
+  "version": "0.0.1",
+  "description": "Streamlined portable webrtc management of p2p and client2server.",
+  "keywords": [
+    "webrtc",
+    "expressjs",
+    "nodejs",
+    "browser"
+  ],
+  "type": "module",
+  "imports": {
+    "#wrtc": {
+      "node": "@roamhq/wrtc",
+      "default": "./lib/browser-wrtc.js"
+    }
+  },
+  "exports": {
+    ".": "./index.mjs",
+    "./router": "./lib/router.js"
+  },
+  "scripts": {
+    "test": "npx jasmine",
+    "testServer": "node testServer.js",
+    "stopServer": "pkill webrtcTestServer"
+  },
+  "dependencies": {
+    "@roamhq/wrtc": "^0.9.1"
+  },
+  "devDependencies": {
+    "express": "^5.2.1",
+    "jasmine": "^5.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kilroy-code/flexstore.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }  
+}

package/routes/index.js

@@ -0,0 +1,61 @@
+import express from 'express';
+import { PromiseWebRTC, TrickleWebRTC } from '../index.js';
+export const router = express.Router();
+
+const testConnections = {}; // Is it really necessary to keep these around, against garbage collection?
+router.post('/promise/echo/:tag', async (req, res, next) => { // Test endpoint for WebRTC.
+  // Client posts collected signal data to us.
+  // We create a WebRTC connection here with the given tag, and answer our response signals.
+  // We also create message handler on the channel that just sends back whatever comes over
+  // from the other side.
+  const {params, body} = req;
+  const tag = params.tag;
+  const signals = body;
+  const connection = testConnections[tag] = new PromiseWebRTC({label: tag});
+  const timer = setTimeout(() => connection.close(), 15e3);
+  const dataPromise = connection.getDataChannelPromise('echo');
+  dataPromise.then(dataChannel => {
+    dataChannel.onclose = () => {
+      clearTimeout(timer);
+      connection.close();
+      delete testConnections[tag];
+    };
+    dataChannel.onmessage = event => dataChannel.send(event.data); // Just echo what we are given.
+  });
+  connection.signals = signals; // Convey the posted offer+ice signals to our connection.
+  res.send(await connection.signals); // Send back our signalling answer+ice.
+});
+router.post('/trickle/echo/:tag', async (req, res, next) => { // Test endpoint for WebRTC.
+  // Same as above, but using trickle ice. The server "peer" is created first and given
+  // the initial offer as above. But then the client reposts (long polling) to give
+  // ice candidates and the server waits until there are any to give back (or connection).
+  const {params, body} = req;
+  const tag = params.tag;
+  const incomingSignals = body;
+  let connection = testConnections[tag];
+  console.log('post connection:', !!connection, 'incoming:', incomingSignals.map(s => s[0]));
+  if (!connection) {
+    connection = testConnections[tag] = TrickleWebRTC.ensure({serviceLabel: tag});
+    const timer = setTimeout(() => connection.close(), 15e3);
+    console.log('created connection and applying', incomingSignals.map(s => s[0]));
+    connection.next = connection.signals;
+    const dataPromise = connection.dataChannelPromise = connection.ensureDataChannel('echo', {}, incomingSignals);
+    dataPromise.then(dataChannel => {
+      connection.reportConnection(true);
+      dataChannel.onclose = () => {
+	clearTimeout(timer);
+	connection.close();
+	delete testConnections[tag];
+      };
+      dataChannel.onmessage = event => dataChannel.send(event.data); // Just echo what we are given.
+    });
+  } else {
+    console.log('applying incoming signals');
+    connection.signals = incomingSignals;
+  }
+  console.log('awaiting response');
+  const responseSignals = await Promise.race([connection.next, connection.dataChannelPromise]);
+  connection.next = connection.signals;
+  console.log('responding', responseSignals.map(s => s[0]));
+  res.send(responseSignals); // Send back our signalling answer+ice.
+});

package/spec/support/jasmine.mjs

@@ -0,0 +1,14 @@
+export default {
+  spec_dir: "spec",
+  spec_files: [
+    "**/*[sS]pec.?(m)js"
+  ],
+  helpers: [
+    "helpers/**/*.?(m)js"
+  ],
+  env: {
+    stopSpecOnExpectationFailure: false,
+    random: true,
+    forbidDuplicateNames: true
+  }
+}

package/spec/webrtcSpec.js

@@ -0,0 +1,230 @@
+const { describe, it, expect, beforeAll, afterAll, beforeEach, afterEach} = globalThis; // For linters.
+import { WebRTC, PromiseWebRTC, TrickleWebRTC } from '../index.js';
+
+class DirectSignaling extends WebRTC {
+  signal(type, message) { // Just invoke the method directly on the otherSide.
+    this.otherSide[type](message);
+  }
+  signals = [];
+}
+function delay(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function fetchSignals(url, signalsToSend) {
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(signalsToSend)
+  });
+  return await response.json();
+}
+function map(signals) { return signals?.map?.(s => s[0]); }
+
+describe("WebRTC", function () {
+  describe("connection to server", function () {
+    describe("using PromiseWebRTC", function () {
+      let connection, dataChannel;
+      beforeAll(async function () {
+	connection = PromiseWebRTC.ensure({serviceLabel: 'PromiseClient'});
+	const dataChannelPromise = connection.ensureDataChannel('echo');
+	connection.signals = await fetchSignals("http://localhost:3000/test/promise/echo/foo", await connection.signals);
+	dataChannel = await dataChannelPromise;
+	connection.reportConnection(true);
+      });
+      afterAll(function () {
+	connection.close();
+      });
+      it("sends and receives data", async function () {
+	const echoPromise = new Promise(resolve => dataChannel.onmessage = event => resolve(event.data));
+	dataChannel.send('hello');
+	expect(await echoPromise).toBe('hello');
+      });
+    });
+    describe("using trickle ICE", function () {
+      let connection, dataChannel;
+      beforeAll(async function () {
+	connection = TrickleWebRTC.ensure({serviceLabel: 'Client'});
+	const dataChannelPromise = connection.ensureDataChannel('echo');
+	await connection.signals;
+	async function exchange() {
+	  if (connection.peer.iceGatheringState !== 'gathering') return;
+	  const sending = connection.sending;
+	  connection.sending = [];
+
+	  console.log('client sending', map(sending));
+	  const returning = await fetchSignals("http://localhost:3000/test/trickle/echo/foo", sending);
+
+	  if (!returning?.length) return;
+	  //if (a.connection.peer.iceGatheringState !== 'gathering') return;
+	  console.log('client', 'received', map(returning), connection.peer.iceGatheringState);
+	  connection.signals = returning;
+	  exchange();
+	}
+	exchange();
+	
+	dataChannel = await dataChannelPromise;
+	connection.reportConnection(true);
+      });
+      afterAll(function () {
+	connection.close();
+      });
+      it("sends and receives data", async function () {
+	const echoPromise = new Promise(resolve => dataChannel.onmessage = event => resolve(event.data));
+	dataChannel.send('hello');
+	expect(await echoPromise).toBe('hello');
+      });
+    });    
+  });
+
+  describe('connection between two peers on the same computer', function () {
+    function test(Kind) {
+      describe(Kind.name, function () {
+	let a = {}, b = {};
+	const channelName = 'test';
+	const channelOptions = {};
+	beforeAll(async function () {
+	  const debug = false;
+	  a.connection = Kind.ensure({serviceLabel: 'A'+Kind.name, debug});
+	  b.connection = Kind.ensure({serviceLabel: 'B'+Kind.name, debug});
+
+	  // Required only for DirectSignaling signal(), above. Ignored for others.
+	  a.connection.otherSide = b.connection;
+	  b.connection.otherSide = a.connection;    
+
+	  let aPromise = a.connection.signals;
+	  a.dataChannelPromise = a.connection.ensureDataChannel(channelName, channelOptions);
+	  const aSignals = await aPromise;
+	  a.connection.sending = [];
+	  //console.log(Kind.name, 'aSignals:', map(aSignals));
+
+	  // The second peer on the initial negotiation must specify a non-empty signals --
+	  // either an empty list for trickle-ice, or a list of the actual signals from the PromiseWebRTC.
+
+	  b.next = b.connection.signals;
+	  // let bPromise = b.connection.signals;
+	  // aPromise = a.connection.signals;
+	  b.dataChannelPromise = b.connection.ensureDataChannel(channelName, channelOptions, aSignals);
+	  // const bSignals = await bPromise;
+	  // console.log(Kind.name, 'bSignals:', map(bSignals));
+
+	  // bPromise = b.connection.signals;
+	  // a.connection.signals = bSignals;
+
+	  async function exchange() {
+	    if (a.connection.peer.iceGatheringState !== 'gathering') return;
+	    const sending = a.connection.sending;
+	    a.connection.sending = [];
+
+	    console.log(Kind.name, 'sending', map(sending), b.connection.peer.iceGatheringState);
+	    b.connection.signals = sending;
+	    const returning = await Promise.race([b.next, b.dataChannelPromise]);
+	    b.next = b.connection.signals;
+
+	    if (!returning?.length) return;
+	    //if (a.connection.peer.iceGatheringState !== 'gathering') return;
+	    console.log(Kind.name, 'received', map(returning), a.connection.peer.iceGatheringState);
+	    a.connection.signals = returning;
+	    exchange();
+	  }
+	  exchange();
+
+	  // Only needed in the trickle ice case. Harmless otherwise.
+	  async function conveySignals(from, to, promise) {
+	    const state = from.peer.iceGatheringState;
+	    if (state !== 'gathering') {
+	      console.log(Kind.name, from.label, state, 'skipping');
+	      return;
+	    }
+	    console.log(Kind.name, from.label, state, from.peer.iceConnectionState, from.peer.connectionState, from.peer.signalingState, 'waiting');
+	    const signals = await Promise.race([promise,
+						from === a.connection ? a.dataChannelPromise : b.dataChannelPromise,
+					       ]); // 7     |      f
+	    console.log(Kind.name, from.label, 'resolved:', map(signals));
+	    const next = from.signals;     // 8     |      g
+	    if (!signals?.length) return;
+	    to.signals = signals;          // d     |       h
+	    conveySignals(from, to, next);
+	  }
+	  // conveySignals(a.connection, b.connection, aNext); //6.5
+	  // conveySignals(b.connection, a.connection, bNext);
+
+	  async function push() { // Await signals in a and send them to b.
+	    if (a.connection.peer.iceGatheringState !== 'gathering') return;
+	    const signals = await Promise.race([aPromise, a.dataChannelPromise]);
+	    aPromise = a.connection.signals;
+	    if (!signals.length) return;
+	    console.log(Kind.name, 'pushing', map(signals));
+	    b.connection.signals = signals;
+	    push();
+	  }
+	  async function pull(promise) { // Request signals from b, setting whatever we get.
+	    if (a.connection.peer.iceGatheringState !== 'gathering') return;	    
+	    const signals = await Promise.race([bPromise, b.dataChannelPromise]);
+	    bPromise = b.connection.signals;
+	    if (!signals.length) return;
+	    console.log(Kind.name, 'pulling', map(signals));
+	    a.connection.signals = signals;
+	    pull();
+	  }
+	  //push();
+	  //pull();
+	  
+	  a.testChannel = await a.dataChannelPromise;
+	  b.testChannel = await b.dataChannelPromise;
+
+	  await a.connection.reportConnection(true);
+	  await b.connection.reportConnection(true);
+	});
+	afterAll(async function () {
+	  a.connection.close();
+	  expect(a.connection.peer.connectionState).toBe('new');
+	  await delay(10); // Yield to allow the other side to close.
+	  expect(b.connection.peer.connectionState).toBe('new');
+	});
+	it("changes state appropriately.", async function () {
+	  expect(await a.dataChannelPromise).toBeTruthy();
+	  expect(await b.dataChannelPromise).toBeTruthy();
+	  expect(a.connection.peer.connectionState).toBe('connected');
+	  expect(b.connection.peer.connectionState).toBe('connected');
+	  expect(a.connection.protocol).toBe(b.connection.protocol);
+	  expect(a.connection.protocol).toBe('udp');
+	  // In this case, since both are on the same machine:
+	  expect(a.connection.candidateType).toBe(b.connection.candidateType);
+	  expect(a.connection.candidateType).toBe('host');
+	  
+	});
+	it("sends data over raw channel.", async function () {
+	  const aReceived = new Promise(resolve => a.testChannel.onmessage = event => resolve(event.data));
+	  const bReceived = new Promise(resolve => b.testChannel.onmessage = event => resolve(event.data));
+	  a.testChannel.send("forty-two");
+	  b.testChannel.send("17");
+	  expect(await aReceived).toBe("17");
+	  expect(await bReceived).toBe("forty-two");
+	});
+	describe("second channel", function () {
+	  beforeAll(async function () {
+	    const name2 = 'channel2';
+	    a.promise2 = a.connection.ensureDataChannel(name2, channelOptions);
+	    b.promise2 = b.connection.ensureDataChannel(name2, channelOptions);
+	    a.channel2 = await a.promise2;
+	    b.channel2 = await b.promise2;
+	  });
+	  afterAll(async function () {
+	    a.channel2.close();
+	  });
+	  it("handles data.", async function () {
+	    const aReceived = new Promise(resolve => a.channel2.onmessage = event => resolve(event.data));
+	    const bReceived = new Promise(resolve => b.channel2.onmessage = event => resolve(event.data));
+	    a.channel2.send("red");
+	    b.channel2.send("blue");
+	    expect(await aReceived).toBe("blue");
+	    expect(await bReceived).toBe("red");
+	  }, 10e3);
+	});
+      });
+    }
+    test(DirectSignaling);
+    test(PromiseWebRTC);
+    test(TrickleWebRTC);
+  });
+});

package/testServer.js

@@ -0,0 +1,14 @@
+import express from 'express';
+import http from 'http';
+import { router } from './routes/index.js';
+
+process.title = 'webrtcTestServer';
+export const app = express();
+const port = 3000;
+app.set('port', port);
+
+app.use(express.json());
+app.use('/test', router);
+
+app.listen(port);
+