ep_webrtc 1.0.0 → 2.0.1

package/README.md

@@ -74,20 +74,6 @@ Supported values for `"disabled"`:
 * `"soft"`: Initially disabled by default.
 * `"hard"`: Unavailable (it cannot be enabled).
 
-The camera's record resolution can be configured by setting `videoConstraints`
-to any [video
-constraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#parameters)
-value acceptable to client browsers. It has the following default value:
-
-```json
-  "ep_webrtc": {
-    "videoConstraints": {
-      "width": {"ideal": 160},
-      "height": {"ideal": 120}
-    }
-  }
-```
-
 ### Custom Activate Button
 
 The misnamed `listenClass` setting allows you to specify a CSS selector for an
@@ -134,6 +120,8 @@ example:
   }
 ```
 
+#### Ephemeral credentials
+
 To limit abuse, the [coturn](https://github.com/coturn/coturn) TURN server
 supports [ephemeral (temporary) usernames and
 passwords](https://github.com/coturn/coturn/blob/60e7a199fe748cb7080594a458d22c2f7bb15a8c/README.turnserver#L664-L729).
@@ -165,13 +153,83 @@ Example:
         "lifetime": 3600
       }
     ]
-  }
+  },
+```
+
+There is also support for ephemeral credentials from the
+[Xirsys](https://xirsys.com/) [API](https://docs.xirsys.com/?pg=api-turn):
+
+  * `credentialType` (required): Must be set to the exact string `"xirsys
+    ephemeral credentials"`.
+  * `url` (required): The desired Xirsys TURN API endpoint.
+  * `username` (required): Your Xirsys username.
+  * `credential` (required): Your Xirsys API secret.
+  * `lifetime` (optional; defaults to 43200 = 12 hours): How long (in seconds)
+    the ephemeral credentials will remain valid after the user visits a pad.
+    After this amount of time, new TURN connections will fail until the user
+    reloads the page (which will generate a new password).
+
+Example:
+
+```json
+  "ep_webrtc": {
+    "iceServers": [
+      {
+        "credentialType": "xirsys ephemeral credentials",
+        "url": "https://global.xirsys.net/_turn/myChannel",
+        "username": "myUsername",
+        "credential": "myPassword",
+        "lifetime": 3600
+      }
+    ]
+  },
 ```
 
+### Microphone Settings
+
+The microphone can be configured by setting `audio.constraints` to any [audio
+constraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#parameters)
+value acceptable to client browsers. It has the following default value:
+
+```json
+  "ep_webrtc": {
+    "audio": {
+      "constraints": {
+        "autoGainControl": {"ideal": true},
+        "echoCancellation": {"ideal": true},
+        "noiseSuppression": {"ideal": true}
+      }
+    }
+  },
+```
+
+For a full list of available constraints, see [the
+standard](https://www.w3.org/TR/2022/CRD-mediacapture-streams-20220307/#constrainable-properties).
+
 ### Video Sizes
 
-To set a custom small and/or large size in pixels, for the video displays, set
-one or both of the following in your `settings.json`:
+The camera's record resolution can be configured by setting `video.constraints`
+to any [video
+constraints](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#parameters)
+value acceptable to client browsers. It has the following default value:
+
+```json
+  "ep_webrtc": {
+    "video": {
+      "constraints": {
+        "width": {"ideal": 160},
+        "height": {"ideal": 120}
+      }
+    }
+  },
+```
+
+For a full list of available constraints, see [the
+standard](https://www.w3.org/TR/2022/CRD-mediacapture-streams-20220307/#constrainable-properties).
+
+Changing the record resolution does not change the size of the displayed video
+widgets. To change the video widget size, set `video.sizes.small` and/or
+`video.sizes.large`:
 
 ```json
   "ep_webrtc": {
@@ -181,12 +239,9 @@ one or both of the following in your `settings.json`:
         "large": 400
       }
     }
-  }
+  },
 ```
 
-This only controls the size of the video display widget. To set the camera's
-record resolution, see the `videoConstraints` setting.
-
 ## Metrics
 
 You can see metrics for various errors that users have when attempting to

package/ep.json

@@ -5,6 +5,7 @@
       "hooks": {
         "clientVars": "",
         "handleMessage": "",
+        "init_ep_webrtc": "",
         "loadSettings": "",
         "socketio": ":setSocketIO",
         "eejsBlock_mySettings": "",

package/index.js

@@ -14,34 +14,54 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+const _ = require('lodash');
+const {Buffer} = require('buffer');
 const crypto = require('crypto');
-const log4js = require('ep_etherpad-lite/node_modules/log4js');
-const statsLogger = log4js.getLogger('stats');
-const configLogger = log4js.getLogger('configuration');
 const eejs = require('ep_etherpad-lite/node/eejs/');
 const sessioninfos = require('ep_etherpad-lite/node/handler/PadMessageHandler').sessioninfos;
 const stats = require('ep_etherpad-lite/node/stats');
+const util = require('util');
 
-const settings = {
+let logger = {};
+for (const level of ['debug', 'info', 'warn', 'error']) {
+  logger[level] = console[level].bind(console, 'ep_webrtc:');
+}
+
+const defaultSettings = {
   // The defaults here are overridden by the values in the `ep_webrtc` object from `settings.json`.
   enabled: true,
   audio: {
+    constraints: {
+      autoGainControl: {ideal: true},
+      echoCancellation: {ideal: true},
+      noiseSuppression: {ideal: true},
+    },
     disabled: 'none',
   },
   video: {
+    constraints: {
+      width: {ideal: 160},
+      height: {ideal: 120},
+    },
     disabled: 'none',
     sizes: {large: 260, small: 160},
   },
-  videoConstraints: {
-    width: {ideal: 160},
-    height: {ideal: 120},
-  },
   iceServers: [{urls: ['stun:stun.l.google.com:19302']}],
   listenClass: null,
   moreInfoUrl: {},
 };
+let settings = null;
 let socketio;
 
+const addContextToError = (err, pfx) => {
+  const newErr = new Error(`${pfx}${err.message}`, {cause: err});
+  if (Error.captureStackTrace) Error.captureStackTrace(newErr, addContextToError);
+  // Check for https://github.com/tc39/proposal-error-cause support, available in Node.js >= v16.10.
+  if (newErr.cause === err) return newErr;
+  err.message = `${pfx}${err.message}`;
+  return err;
+};
+
 // Copied from:
 // https://github.com/ether/etherpad-lite/blob/f95b09e0b6752a0d226d58d8b246831164dc9533/src/node/handler/PadMessageHandler.js#L1411-L1420
 const _getRoomSockets = (padId) => {
@@ -102,21 +122,70 @@ const handleErrorStatMessage = (statName) => {
   if (statErrorNames.includes(statName)) {
     stats.meter(`ep_webrtc_err_${statName}`).mark();
   } else {
-    statsLogger.warn(`Invalid ep_webrtc error stat: ${statName}`);
+    logger.warn(`Invalid ep_webrtc error stat: ${statName}`);
+  }
+};
+
+const fetchJson = async (url, opts = {}) => {
+  const c = new globalThis.AbortController();
+  const t = setTimeout(() => c.abort(), 5000);
+  let res;
+  try {
+    res = await globalThis.fetch(url, {signal: c.signal, ...opts});
+  } finally {
+    clearTimeout(t);
   }
+  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+  return await res.json();
 };
 
 exports.clientVars = async (hookName, {clientVars: {userId: authorId}}) => ({ep_webrtc: {
   ...settings,
-  iceServers: settings.iceServers.map((server) => {
-    if (server.credentialType !== 'coturn ephemeral password') return server;
-    const {lifetime = 60 * 60 * 12 /* seconds */} = server;
-    const username = `${Math.floor(Date.now() / 1000) + lifetime}:${authorId}`;
-    const hmac = crypto.createHmac('sha1', server.credential);
-    hmac.update(username);
-    const credential = hmac.digest('base64');
-    return {urls: server.urls, username, credential};
-  }),
+  iceServers: await Promise.all(settings.iceServers.map(async (server) => {
+    switch (server.credentialType) {
+      case 'coturn ephemeral password': {
+        const {lifetime = 60 * 60 * 12 /* seconds */} = server;
+        const username = `${Math.floor(Date.now() / 1000) + lifetime}:${authorId}`;
+        const hmac = crypto.createHmac('sha1', server.credential);
+        hmac.update(username);
+        const credential = hmac.digest('base64');
+        return {urls: server.urls, username, credential};
+      }
+      case 'xirsys ephemeral credentials': {
+        const {
+          url,
+          username,
+          credential,
+          lifetime: expire = 12 * 60 * 60, // seconds
+          method = 'PUT',
+          headers: h = {},
+          jsonBody: b = {},
+        } = server;
+        // Can't set default values for the Content-Type and Authorization headers by using an
+        // object literal with spread (e.g., `{'content-type': 'foo', ...h}`) because the Headers
+        // constructor uses `.append()` internally instead of `.set()`. This matters if a header is
+        // repeated multiple times by using different mixes of upper- and lower-case letters.
+        const headers = new globalThis.Headers(h);
+        if (!headers.has('content-type')) headers.set('content-type', 'application/json');
+        if (username && !headers.has('authorization')) {
+          headers.set('authorization',
+              `Basic ${Buffer.from(`${username}:${credential}`).toString('base64')}`);
+        }
+        const body =
+            JSON.stringify(b && typeof b === 'object' ? {format: 'urls', expire, ...b} : b);
+        try {
+          const {v, s} = await fetchJson(url, {method, headers, body});
+          if (s !== 'ok') throw new Error(`API error: ${v}`);
+          return v.iceServers;
+        } catch (err) {
+          const newErr = addContextToError(err, 'failed to get TURN credentials: ');
+          logger.error(newErr.stack || newErr.toString());
+          throw newErr;
+        }
+      }
+      default: return server;
+    }
+  })),
 }});
 
 exports.handleMessage = async (hookName, {message, socket}) => {
@@ -130,6 +199,22 @@ exports.handleMessage = async (hookName, {message, socket}) => {
   }
 };
 
+exports.init_ep_webrtc = async (hookName, {logger: l}) => {
+  if (l != null) logger = l;
+  // TODO: Remove this once all supported Node.js versions have the fetch API (added in Node.js
+  // v17.5.0 behind the --experimental-fetch flag).
+  if (!globalThis.fetch) {
+    // eslint-disable-next-line node/no-unsupported-features/es-syntax -- https://github.com/mysticatea/eslint-plugin-node/issues/250
+    const {default: fetch, Headers, Request, Response} = await import('node-fetch');
+    Object.assign(globalThis, {fetch, Headers, Request, Response});
+  }
+  // TODO: Remove this once all supported Node.js versions have AbortController (>= v15.4.0).
+  if (!globalThis.AbortController) {
+    // eslint-disable-next-line node/no-unsupported-features/es-syntax -- https://github.com/mysticatea/eslint-plugin-node/issues/250
+    globalThis.AbortController = (await import('abort-controller')).default;
+  }
+};
+
 exports.setSocketIO = (hookName, {io}) => { socketio = io; };
 
 exports.eejsBlock_mySettings = (hookName, context) => {
@@ -143,27 +228,23 @@ exports.eejsBlock_styles = (hookName, context) => {
   context.content += eejs.require('./templates/styles.html', {}, module);
 };
 
-exports.loadSettings = async (hookName, {settings: {ep_webrtc = {}}}) => {
-  const isObj = (o) => o != null && typeof o === 'object' && !Array.isArray(o);
-  const merge = (target, source) => {
-    for (const [k, sv] of Object.entries(source)) {
-      const tv = target[k];
-      // The own-property check on the target prevents prototype pollution. (Prototype pollution
-      // shouldn't be exploitable here because the source comes from admin-controlled settings.json,
-      // but the check is added anyway to hopefully pacify static analysis tools.)
-      if (Object.prototype.hasOwnProperty.call(target, k) && isObj(tv) && isObj(sv)) merge(tv, sv);
-      else target[k] = sv;
-    }
-  };
-  merge(settings, ep_webrtc);
+exports.loadSettings = async (hookName, {settings: {ep_webrtc: s = {}}}) => {
+  settings = _.mergeWith({}, defaultSettings, s, (objV, srcV, key, obj, src) => {
+    if (Array.isArray(srcV)) return _.cloneDeep(srcV); // Don't merge arrays, replace them.
+    if (src === s.video && key === 'constraints') return _.cloneDeep(srcV);
+  });
   settings.configError = (() => {
     for (const k of ['audio', 'video']) {
       const {[k]: {disabled} = {}} = settings;
       if (disabled != null && !['none', 'hard', 'soft'].includes(disabled)) {
-        configLogger.error(`Invalid value in settings.json for ep_webrtc.${k}.disabled`);
+        logger.error(`Invalid value in settings.json for ep_webrtc.${k}.disabled`);
         return true;
       }
     }
     return false;
   })();
+  logger.info('configured:', util.inspect({
+    ...settings,
+    iceServers: settings.iceServers.map((s) => s.credential ? {...s, credential: '*****'} : s),
+  }, {depth: Infinity}));
 };

package/package.json

@@ -5,21 +5,25 @@
     "url": "git@github.com:ether/ep_webrtc.git",
     "type": "git"
   },
-  "version": "1.0.0",
+  "version": "2.0.1",
   "description": "WebRTC based audio/video chat to Etherpad",
   "author": "John McLear <john@mclear.co.uk>",
   "contributors": [],
   "engines": {
     "node": ">=12.17.0"
   },
-  "dependencies": {},
+  "dependencies": {
+    "abort-controller": "^3.0.0",
+    "lodash": "^4.17.21",
+    "node-fetch": "^3.2.1"
+  },
   "funding": {
     "type": "individual",
     "url": "https://etherpad.org/"
   },
   "devDependencies": {
     "eslint": "^8.10.0",
-    "eslint-config-etherpad": "^3.0.4",
+    "eslint-config-etherpad": "^3.0.5",
     "typescript": "^4.6.2"
   },
   "scripts": {

package/static/js/adapter.js

@@ -2405,7 +2405,7 @@ function shimCreateOfferLegacy(window) {
           }
         }
       } else if (offerOptions.offerToReceiveAudio === true && !audioTransceiver) {
-        this.addTransceiver('audio');
+        this.addTransceiver('audio', { direction: 'recvonly' });
       }
 
       if (typeof offerOptions.offerToReceiveVideo !== 'undefined') {
@@ -2430,7 +2430,7 @@ function shimCreateOfferLegacy(window) {
           }
         }
       } else if (offerOptions.offerToReceiveVideo === true && !videoTransceiver) {
-        this.addTransceiver('video');
+        this.addTransceiver('video', { direction: 'recvonly' });
       }
     }
     return origCreateOffer.apply(this, arguments);

package/static/js/index.js

@@ -668,8 +668,8 @@ exports.rtc = new class {
         if (!addAudioTrack && !addVideoTrack) return new MediaStream();
         debug(`requesting permission to access ${devices.join(' and ')}`);
         const stream = await window.navigator.mediaDevices.getUserMedia({
-          audio: addAudioTrack,
-          video: addVideoTrack && this._settings.videoConstraints,
+          audio: addAudioTrack && this._settings.audio.constraints,
+          video: addVideoTrack && this._settings.video.constraints,
         });
         debug('successfully accessed device(s)');
         return stream;