ep_webrtc 0.1.99 → 1.1.0

package/.github/workflows/backend-tests.yml

@@ -22,12 +22,12 @@ jobs:
           sudo apt install -y --no-install-recommends libreoffice libreoffice-pdfimport
       -
         name: Install etherpad core
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: ether/etherpad-lite
       -
         name: Checkout plugin repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: ./node_modules/__tmp
       -

package/.github/workflows/frontend-tests.yml

@@ -28,7 +28,7 @@ jobs:
           printf %s\\n '::set-output name=tunnel_id::${{ github.run_id }}-${{ github.run_number }}-${{ github.job }}'
       -
         name: Check out Etherpad core
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: ether/etherpad-lite
       -
@@ -41,7 +41,7 @@ jobs:
             src/bin/doc/package-lock.json
       -
         name: Check out the plugin
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           path: ./node_modules/__tmp
       -

package/.github/workflows/npmpublish.yml

@@ -22,7 +22,7 @@ jobs:
       # conflicts with this plugin's clone, etherpad-lite must be cloned and
       # moved out before this plugin's repo is cloned to $GITHUB_WORKSPACE.
       -
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           repository: ether/etherpad-lite
           path: etherpad-lite
@@ -31,7 +31,7 @@ jobs:
       # etherpad-lite has been moved outside of $GITHUB_WORKSPACE, so it is now
       # safe to clone this plugin's repo to $GITHUB_WORKSPACE.
       -
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
       # This is necessary for actions/setup-node because '..' can't be used in
       # cache-dependency-path.
       -
@@ -77,7 +77,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       -
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           fetch-depth: 0
       -

package/README.md

@@ -74,6 +74,20 @@ 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
@@ -120,6 +134,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).
@@ -151,7 +167,36 @@ 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
+      }
+    ]
+  },
 ```
 
 ### Video Sizes
@@ -170,6 +215,9 @@ one or both of the following in your `settings.json`:
   }
 ```
 
+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,15 +14,19 @@
  * 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 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: {
@@ -32,12 +36,26 @@ const settings = {
     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) => {
@@ -98,21 +116,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}) => {
@@ -126,6 +193,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) => {
@@ -139,27 +222,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 && key === 'videoConstraints') 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:', {
+    ...settings,
+    iceServers: settings.iceServers.map((s) => s.credential ? {...s, credential: '*****'} : s),
+  });
 };

package/package.json

@@ -5,22 +5,26 @@
     "url": "git@github.com:ether/ep_webrtc.git",
     "type": "git"
   },
-  "version": "0.1.99",
+  "version": "1.1.0",
   "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.9.0",
-    "eslint-config-etherpad": "^3.0.1",
-    "typescript": "^4.5.5"
+    "eslint": "^8.10.0",
+    "eslint-config-etherpad": "^3.0.5",
+    "typescript": "^4.6.2"
   },
   "scripts": {
     "lint": "eslint .",

package/static/js/index.js

@@ -669,7 +669,7 @@ exports.rtc = new class {
         debug(`requesting permission to access ${devices.join(' and ')}`);
         const stream = await window.navigator.mediaDevices.getUserMedia({
           audio: addAudioTrack,
-          video: addVideoTrack && {width: {ideal: 320}, height: {ideal: 240}},
+          video: addVideoTrack && this._settings.videoConstraints,
         });
         debug('successfully accessed device(s)');
         return stream;