Source: bridge.js

  1. "use strict";
  3. const Datastore = require("nedb");
  4. const Promise = require("bluebird");
  5. const fs = require("fs");
  6. const util = require("util");
  7. const yaml = require("js-yaml");
  9. const AppServiceRegistration = require("matrix-appservice").AppServiceRegistration;
  10. const AppService = require("matrix-appservice").AppService;
  11. const MatrixScheduler = require("matrix-js-sdk").MatrixScheduler;
  13. const BridgeContext = require("./components/bridge-context");
  14. const ClientFactory = require("./components/client-factory");
  15. const AppServiceBot = require("./components/app-service-bot");
  16. const RequestFactory = require("./components/request-factory");
  17. const Intent = require("./components/intent");
  18. const RoomBridgeStore = require("./components/room-bridge-store");
  19. const UserBridgeStore = require("./components/user-bridge-store");
  20. const EventBridgeStore = require("./components/event-bridge-store");
  21. const MatrixUser = require("./models/users/matrix");
  22. const MatrixRoom = require("./models/rooms/matrix");
  23. const PrometheusMetrics = require("./components/prometheusmetrics");
  24. const MembershipCache = require("./components/membership-cache");
  25. const RoomLinkValidator = require("./components/room-link-validator").RoomLinkValidator;
  26. const RLVStatus = require("./components/room-link-validator").validationStatuses;
  27. const RoomUpgradeHandler = require("./components/room-upgrade-handler");
  28. const EventNotHandledError = require("./errors").EventNotHandledError;
  29. const InternalError = require("./errors").InternalError;
  30. const EventQueue = require("./components/event-queue").EventQueue;
  32. const log = require("./components/logging").get("bridge");
  34. // The frequency at which we will check the list of accumulated Intent objects.
  35. const INTENT_CULL_CHECK_PERIOD_MS = 1000 * 60; // once per minute
  36. // How long a given Intent object can hang around unused for.
  37. const INTENT_CULL_EVICT_AFTER_MS = 1000 * 60 * 15; // 15 minutes
  39. /**
  40.  * @constructor
  41.  * @param {Object} opts Options to pass to the bridge
  42.  * @param {AppServiceRegistration|string} opts.registration Application service
  43.  * registration object or path to the registration file.
  44.  * @param {string} opts.homeserverUrl The base HS url
  45.  * @param {string} opts.domain The domain part for user_ids and room aliases
  46.  * e.g. "bar" in "@foo:bar".
  47.  * @param {string} opts.networkName A human readable string that will be used when
  48.  * the bridge signals errors to the client. Will not include in error events if ommited.
  49.  * @param {Object} opts.controller The controller logic for the bridge.
  50.  * @param {Bridge~onEvent} opts.controller.onEvent Function. Called when
  51.  * an event has been received from the HS.
  52.  * @param {Bridge~onUserQuery=} opts.controller.onUserQuery Function. If supplied,
  53.  * the bridge will invoke this function when queried via onUserQuery. If
  54.  * not supplied, no users will be provisioned on user queries. Provisioned users
  55.  * will automatically be stored in the associated <code>userStore</code>.
  56.  * @param {Bridge~onAliasQuery=} opts.controller.onAliasQuery Function. If supplied,
  57.  * the bridge will invoke this function when queried via onAliasQuery. If
  58.  * not supplied, no rooms will be provisioned on alias queries. Provisioned rooms
  59.  * will automatically be stored in the associated <code>roomStore</code>.
  60.  * @param {Bridge~onAliasQueried=} opts.controller.onAliasQueried Function.
  61.  * If supplied, the bridge will invoke this function when a room has been created
  62.  * via onAliasQuery.
  63.  * @param {Bridge~onLog=} opts.controller.onLog Function. Invoked when
  64.  * logging. Defaults to a function which logs to the console.
  65.  * @param {Bridge~thirdPartyLookup=} opts.controller.thirdPartyLookup Object. If
  66.  * supplied, the bridge will respond to third-party entity lookups using the
  67.  * contained helper functions.
  68.  * @param {Bridge~onRoomUpgrade=} opts.controller.onRoomUpgrade Function. If
  69.  * supplied, the bridge will invoke this function when it sees an upgrade event
  70.  * for a room.
  71.  * @param {(RoomBridgeStore|string)=} opts.roomStore The room store instance to
  72.  * use, or the path to the room .db file to load. A database will be created if
  73.  * this is not specified.
  74.  * @param {(UserBridgeStore|string)=} opts.userStore The user store instance to
  75.  * use, or the path to the user .db file to load. A database will be created if
  76.  * this is not specified.
  77.  * @param {(EventBridgeStore|string)=} opts.eventStore The event store instance to
  78.  * use, or the path to the event .db file to load. This will NOT be created if it
  79.  * isn't specified.
  80.  * @param {MembershipCache=} opts.membershipCache The membership cache instance
  81.  * to use, which can be manually created by a bridge for greater control over
  82.  * caching. By default a membership cache will be created internally.
  83.  * @param {boolean=} opts.suppressEcho True to stop receiving onEvent callbacks
  84.  * for events which were sent by a bridge user. Default: true.
  85.  * @param {ClientFactory=} opts.clientFactory The client factory instance to
  86.  * use. If not supplied, one will be created.
  87.  * @param {boolean} opts.logRequestOutcome True to enable SUCCESS/FAILED log lines
  88.  * to be sent to onLog. Default: true.
  89.  * @param {Object=} opts.intentOptions Options to supply to created Intent instances.
  90.  * @param {Object=} opts.intentOptions.bot Options to supply to the bot intent.
  91.  * @param {Object=} opts.intentOptions.clients Options to supply to the client intents.
  92.  * @param {Object=} opts.escapeUserIds Escape userIds for non-bot intents with
  93.  * {@link MatrixUser~escapeUserId}
  94.  * Default: true
  95.  * @param {Object=} opts.queue Options for the onEvent queue. When the bridge
  96.  * receives an incoming transaction, it needs to asyncly query the data store for
  97.  * contextual info before calling onEvent. A queue is used to keep the onEvent
  98.  * calls consistent with the arrival order from the incoming transactions.
  99.  * @param {string=} opts.queue.type The type of queue to use when feeding through
  100.  * to {@link Bridge~onEvent}. One of: "none", single", "per_room". If "none",
  101.  * events are fed through as soon as contextual info is obtained, which may result
  102.  * in out of order events but stops HOL blocking. If "single", onEvent calls will
  103.  * be in order but may be slower due to HOL blocking. If "per_room", a queue per
  104.  * room ID is made which reduces the impact of HOL blocking to be scoped to a room.
  105.  * Default: "single".
  106.  * @param {boolean=} opts.queue.perRequest True to only feed through the next
  107.  * event after the request object in the previous call succeeds or fails. It is
  108.  * <b>vital</b> that you consistently resolve/reject the request if this is 'true',
  109.  * else you will not get any further events from this queue. To aid debugging this,
  110.  * consider setting a delayed listener on the request factory. If false, the mere
  111.  * invockation of onEvent is enough to trigger the next event in the queue.
  112.  * You probably want to set this to 'true' if your {@link Bridge~onEvent} is
  113.  * performing async operations where ordering matters (e.g. messages). Default: false.
  114.  * @param {boolean=} opts.disableContext True to disable {@link Bridge~BridgeContext}
  115.  * parameters in {@link Bridge~onEvent}. Disabling the context makes the
  116.  * bridge do fewer database lookups, but prevents there from being a
  117.  * <code>context</code> parameter. Default: false.
  118.  * @param {boolean=} opts.disableStores True to disable enabling of stores.
  119.  * This should be used by bridges that use their own database instances and
  120.  * do not need any of the included store objects. This implies setting
  121.  * disableContext to True. Default: false.
  122.  * @param {Object=} opts.roomLinkValidation Options to supply to the room link
  123.  * validator. If not defined then all room links are accepted.
  124.  * @param {string} opts.roomLinkValidation.ruleFile A file containing rules
  125.  * on which matrix rooms can be bridged.
  126.  * @param {Object=} opts.roomLinkValidation.rules A object containing rules
  127.  * on which matrix rooms can be bridged. This is used if ruleFile is undefined.
  128.  * @param {boolean=} opts.roomLinkValidation.triggerEndpoint Enable the endpoint
  129.  * to trigger a reload of the rules file.
  130.  * Default: false
  131.  * @param {RoomUpgradeHandler~Options} opts.roomUpgradeOpts Options to supply to
  132.  * the room upgrade handler. If not defined then upgrades are NOT handled by the bridge.
  133.  */
  134. function Bridge(opts) {
  135.     if (typeof opts !== "object") {
  136.         throw new Error("opts must be supplied.");
  137.     }
  138.     var required = [
  139.         "homeserverUrl", "registration", "domain", "controller"
  140.     ];
  141.     required.forEach(function(key) {
  142.         if (!opts[key]) {
  143.             throw new Error("Missing '" + key + "' in opts.");
  144.         }
  145.     });
  146.     if (typeof opts.controller.onEvent !== "function") {
  147.         throw new Error("controller.onEvent is a required function");
  148.     }
  151.     if (opts.disableContext === undefined) {
  152.         opts.disableContext = false;
  153.     }
  155.     if (opts.disableStores === true) {
  156.         opts.disableStores = true;
  157.         opts.disableContext = true;
  158.     }
  159.     else {
  160.         opts.disableStores = false;
  161.     }
  164.     opts.userStore = opts.userStore || "user-store.db";
  165.     opts.roomStore = opts.roomStore || "room-store.db";
  167.     opts.eventStore = opts.eventStore || null; // Must be enabled
  168.     opts.queue = opts.queue || {};
  169.     opts.intentOptions = opts.intentOptions || {};
  170.     opts.queue.type = opts.queue.type || "single";
  171.     if (opts.queue.perRequest === undefined) {
  172.         opts.queue.perRequest = false;
  173.     }
  174.     if (opts.logRequestOutcome === undefined) {
  175.         opts.logRequestOutcome = true;
  176.     }
  178.     // Default: logger -> log to console
  179.     opts.controller.onLog = opts.controller.onLog || function(text, isError) {
  180.         if (isError) {
  181.             log.error(text);
  182.             return;
  183.         }
  184.         log.info(text);
  185.     };
  187.     // Default: suppress echo -> True
  188.     if (opts.suppressEcho === undefined) {
  189.         opts.suppressEcho = true;
  190.     }
  192.     // we'll init these at runtime
  193.     this.appService = null;
  194.     this.opts = opts;
  195.     this._clientFactory = null;
  196.     this._botClient = null;
  197.     this._appServiceBot = null;
  198.     this._requestFactory = null;
  199.     this._botIntent = null;
  200.     this._intents = {
  201.         // user_id + request_id : Intent
  202.     };
  203.     this._intentLastAccessed = Object.create(null); // user_id + request_id : timestamp
  204.     this._intentLastAccessedTimeout = null;
  205.     this._powerLevelMap = {
  206.         // room_id: event.content
  207.     };
  208.     this._membershipCache = opts.membershipCache || new MembershipCache();
  209.     this._intentBackingStore = {
  210.         setMembership: this._membershipCache.setMemberEntry.bind(this._membershipCache),
  211.         setPowerLevelContent: this._setPowerLevelEntry.bind(this),
  212.         getMembership: this._membershipCache.getMemberEntry.bind(this._membershipCache),
  213.         getPowerLevelContent: this._getPowerLevelEntry.bind(this)
  214.     };
  215.     this._queue = EventQueue.create(this.opts.queue, this._onConsume.bind(this));
  216.     this._prevRequestPromise = Promise.resolve();
  217.     this._metrics = null; // an optional PrometheusMetrics instance
  218.     this._roomLinkValidator = null;
  219.     if (opts.roomUpgradeOpts) {
  220.         opts.roomUpgradeOpts.consumeEvent = opts.roomUpgradeOpts.consumeEvent !== false ? true : false;
  221.         if (this.opts.disableStores) {
  222.             opts.roomUpgradeOpts.migrateStoreEntries = false;
  223.         }
  224.         this._roomUpgradeHandler = new RoomUpgradeHandler(opts.roomUpgradeOpts, this);
  225.     }
  226.     else {
  227.         this._roomUpgradeHandler = null;
  228.     }
  229. }
  231. /**
  232.  * Load the user and room databases. Access them via getUserStore() and getRoomStore().
  233.  * @return {Promise} Resolved/rejected when the user/room databases have been loaded.
  234.  */
  235. Bridge.prototype.loadDatabases = function() {
  236.     if (this.disableStores) {
  237.         return Promise.resolve();
  238.     }
  239.     // Load up the databases if they provided file paths to them (or defaults)
  240.     if (typeof this.opts.userStore === "string") {
  241.         this.opts.userStore = loadDatabase(this.opts.userStore, UserBridgeStore);
  242.     }
  243.     if (typeof this.opts.roomStore === "string") {
  244.         this.opts.roomStore = loadDatabase(this.opts.roomStore, RoomBridgeStore);
  245.     }
  246.     if (typeof this.opts.eventStore === "string") {
  247.         this.opts.eventStore = loadDatabase(this.opts.eventStore, EventBridgeStore);
  248.     }
  250.     // This works because if they provided a string we converted it to a Promise
  251.     // which will be resolved when we have the db instance. If they provided a
  252.     // db instance then this will resolve immediately.
  253.     return Promise.all([
  254.         Promise.resolve(this.opts.userStore).then((db) => {
  255.             this._userStore = db;
  256.         }),
  257.         Promise.resolve(this.opts.roomStore).then((db) => {
  258.             this._roomStore = db;
  259.         }),
  260.         Promise.resolve(this.opts.eventStore).then((db) => {
  261.             this._eventStore = db;
  262.         })
  263.     ]);
  264. };
  266. /**
  267.  * Run the bridge (start listening)
  268.  * @param {Number} port The port to listen on.
  269.  * @param {Object} config Configuration options
  270.  * @param {AppService=} appServiceInstance The AppService instance to attach to.
  271.  * If not provided, one will be created.
  272.  * @param {String} hostname Optional hostname to bind to. (e.g. 0.0.0.0)
  273.  */
  274. Bridge.prototype.run = function(port, config, appServiceInstance, hostname) {
  275.     var self = this;
  277.     // Load the registration file into an AppServiceRegistration object.
  278.     if (typeof self.opts.registration === "string") {
  279.         var regObj = yaml.safeLoad(fs.readFileSync(self.opts.registration, 'utf8'));
  280.         self.opts.registration = AppServiceRegistration.fromObject(regObj);
  281.         if (self.opts.registration === null) {
  282.             throw new Error("Failed to parse registration file");
  283.         }
  284.     }
  286.     this._clientFactory = self.opts.clientFactory || new ClientFactory({
  287.         url: self.opts.homeserverUrl,
  288.         token: self.opts.registration.as_token,
  289.         appServiceUserId: (
  290.             "@" + self.opts.registration.sender_localpart + ":" + self.opts.domain
  291.         ),
  292.         clientSchedulerBuilder: function() {
  293.             return new MatrixScheduler(retryAlgorithm, queueAlgorithm);
  294.         },
  295.     });
  296.     this._clientFactory.setLogFunction(function(text, isErr) {
  297.         if (!self.opts.controller.onLog) {
  298.             return;
  299.         }
  300.         self.opts.controller.onLog(text, isErr);
  301.     });
  302.     this._botClient = this._clientFactory.getClientAs();
  303.     this._appServiceBot = new AppServiceBot(
  304.         this._botClient, self.opts.registration, this._membershipCache
  305.     );
  307.     if (this.opts.roomLinkValidation !== undefined) {
  308.         this._roomLinkValidator = new RoomLinkValidator(
  309.             this.opts.roomLinkValidation,
  310.             this._appServiceBot
  311.         );
  312.     }
  314.     this._requestFactory = new RequestFactory();
  315.     if (this.opts.controller.onLog && this.opts.logRequestOutcome) {
  316.         this._requestFactory.addDefaultResolveCallback(function(req, res) {
  317.             self.opts.controller.onLog(
  318.                 "[" + req.getId() + "] SUCCESS (" + req.getDuration() + "ms)"
  319.             );
  320.         });
  321.         this._requestFactory.addDefaultRejectCallback(function(req, err) {
  322.             self.opts.controller.onLog(
  323.                 "[" + req.getId() + "] FAILED (" + req.getDuration() + "ms) " +
  324.                 (err ? util.inspect(err) : "")
  325.             );
  326.         });
  327.     }
  328.     var botIntentOpts = {
  329.         registered: true,
  330.         backingStore: this._intentBackingStore,
  331.     };
  332.     if (this.opts.intentOptions.bot) { // copy across opts
  333.         Object.keys(this.opts.intentOptions.bot).forEach(function(k) {
  334.             botIntentOpts[k] = self.opts.intentOptions.bot[k];
  335.         });
  336.     }
  337.     this._botIntent = new Intent(this._botClient, this._botClient, botIntentOpts);
  338.     this._intents = {
  339.         // user_id + request_id : Intent
  340.     };
  342.     this.appService = appServiceInstance || new AppService({
  343.         homeserverToken: this.opts.registration.getHomeserverToken()
  344.     });
  345.     this.appService.onUserQuery = (userId) => Promise.cast(this._onUserQuery(userId));
  346.     this.appService.onAliasQuery = this._onAliasQuery.bind(this);
  347.     this.appService.on("event", this._onEvent.bind(this));
  348.     this.appService.on("http-log", function(line) {
  349.         if (!self.opts.controller.onLog) {
  350.             return;
  351.         }
  352.         self.opts.controller.onLog(line, false);
  353.     });
  354.     this._customiseAppservice();
  355.     this._setupIntentCulling();
  357.     if (this._metrics) {
  358.         this._metrics.addAppServicePath(this);
  359.     }
  361.     this.appService.listen(port, hostname);
  362.     return this.loadDatabases();
  363. };
  365. /**
  366.  * Apply any customisations required on the appService object.
  367.  */
  368. Bridge.prototype._customiseAppservice = function() {
  369.     if (this.opts.controller.thirdPartyLookup) {
  370.         this._customiseAppserviceThirdPartyLookup(this.opts.controller.thirdPartyLookup);
  371.     }
  372.     if (this.opts.roomLinkValidation && this.opts.roomLinkValidation.triggerEndpoint) {
  373.         this.addAppServicePath({
  374.             method: "POST",
  375.             path: "/_bridge/roomLinkValidator/reload",
  376.             handler: (req, res) => {
  377.                 if (!this._requestCheckToken(req, res)) {
  378.                     return;
  379.                 }
  380.                 try {
  381.                     // Will use filename if provided, or the config
  382.                     // one otherwised.
  383.                     this._roomLinkValidator.readRuleFile(req.query.filename);
  384.                     res.status(200).send("Success");
  385.                 }
  386.                 catch (e) {
  387.                     res.status(500).send("Failed: " + e);
  388.                 }
  389.             },
  390.         });
  391.     }
  392. };
  394. // Set a timer going which will periodically remove Intent objects to prevent
  395. // them from accumulating too much. Removal is based on access time (calls to
  396. // getIntent). Intents expire after INTENT_CULL_EVICT_AFTER_MS of not being called.
  397. Bridge.prototype._setupIntentCulling = function() {
  398.     if (this._intentLastAccessedTimeout) {
  399.         clearTimeout(this._intentLastAccessedTimeout);
  400.     }
  401.     var self = this;
  402.     this._intentLastAccessedTimeout = setTimeout(function() {
  403.         var now = Date.now();
  404.         Object.keys(self._intentLastAccessed).forEach(function(key) {
  405.             if ((self._intentLastAccessed[key] + INTENT_CULL_EVICT_AFTER_MS) < now) {
  406.                 delete self._intentLastAccessed[key];
  407.                 delete self._intents[key];
  408.             }
  409.         });
  410.         self._intentLastAccessedTimeout = null;
  411.         // repeat forever. We have no cancellation mechanism but we don't expect
  412.         // Bridge objects to be continually recycled so this is fine.
  413.         self._setupIntentCulling();
  414.     }, INTENT_CULL_CHECK_PERIOD_MS);
  415. }
  417. Bridge.prototype._customiseAppserviceThirdPartyLookup = function(lookupController) {
  418.     var protocols = lookupController.protocols || [];
  420.     var _respondErr = function(e, res) {
  421.         if (typeof e === "object" && e.code && e.err) {
  422.             res.status(e.code).json({error: e.err});
  423.         }
  424.         else {
  425.             res.status(500).send("Failed: " + e);
  426.         }
  427.     }
  429.     if (lookupController.getProtocol) {
  430.         var getProtocolFunc = lookupController.getProtocol;
  432.         this.addAppServicePath({
  433.             method: "GET",
  434.             path: "/_matrix/app/:ver/thirdparty/protocol/:protocol",
  435.             handler: function(req, res) {
  436.                 if (req.params.ver !== "unstable") {
  437.                     res.status(404).json(
  438.                         {err: "Unrecognised API version " + req.params.ver}
  439.                     );
  440.                     return;
  441.                 }
  443.                 var protocol = req.params.protocol;
  445.                 if (protocols.length && protocols.indexOf(protocol) === -1) {
  446.                     res.status(404).json({err: "Unknown 3PN protocol " + protocol});
  447.                     return;
  448.                 }
  450.                 getProtocolFunc(protocol).then(
  451.                     function(result) { res.status(200).json(result) },
  452.                     function(e) { _respondErr(e, res) }
  453.                 );
  454.             },
  455.         });
  456.     }
  458.     if (lookupController.getLocation) {
  459.         var getLocationFunc = lookupController.getLocation;
  461.         this.addAppServicePath({
  462.             method: "GET",
  463.             path: "/_matrix/app/:ver/thirdparty/location/:protocol",
  464.             handler: function(req, res) {
  465.                 if (req.params.ver !== "unstable") {
  466.                     res.status(404).json(
  467.                         {err: "Unrecognised API version " + req.params.ver}
  468.                     );
  469.                     return;
  470.                 }
  472.                 var protocol = req.params.protocol;
  474.                 if (protocols.length && protocols.indexOf(protocol) === -1) {
  475.                     res.status(404).json({err: "Unknown 3PN protocol " + protocol});
  476.                     return;
  477.                 }
  479.                 getLocationFunc(protocol, req.query).then(
  480.                     function(result) { res.status(200).json(result) },
  481.                     function(e) { _respondErr(e, res) }
  482.                 );
  483.             },
  484.         });
  485.     }
  487.     if (lookupController.parseLocation) {
  488.         var parseLocationFunc = lookupController.parseLocation;
  490.         this.addAppServicePath({
  491.             method: "GET",
  492.             path: "/_matrix/app/:ver/thirdparty/location",
  493.             handler: function(req, res) {
  494.                 if (req.params.ver !== "unstable") {
  495.                     res.status(404).json(
  496.                         {err: "Unrecognised API version " + req.params.ver}
  497.                     );
  498.                     return;
  499.                 }
  501.                 var alias = req.query.alias;
  502.                 if (!alias) {
  503.                     res.status(400).send({err: "Missing 'alias' parameter"});
  504.                     return;
  505.                 }
  507.                 parseLocationFunc(alias).then(
  508.                     function(result) { res.status(200).json(result) },
  509.                     function(e) { _respondErr(e, res) }
  510.                 );
  511.             },
  512.         });
  513.     }
  515.     if (lookupController.getUser) {
  516.         var getUserFunc = lookupController.getUser;
  518.         this.addAppServicePath({
  519.             method: "GET",
  520.             path: "/_matrix/app/:ver/thirdparty/user/:protocol",
  521.             handler: function(req, res) {
  522.                 if (req.params.ver !== "unstable") {
  523.                     res.status(404).json(
  524.                         {err: "Unrecognised API version " + req.params.ver}
  525.                     );
  526.                     return;
  527.                 }
  529.                 var protocol = req.params.protocol;
  531.                 if (protocols.length && protocols.indexOf(protocol) === -1) {
  532.                     res.status(404).json({err: "Unknown 3PN protocol " + protocol});
  533.                     return;
  534.                 }
  536.                 getUserFunc(protocol, req.query).then(
  537.                     function(result) { res.status(200).json(result) },
  538.                     function(e) { _respondErr(e, res) }
  539.                 );
  540.             }
  541.         });
  542.     }
  544.     if (lookupController.parseUser) {
  545.         var parseUserFunc = lookupController.parseUser;
  547.         this.addAppServicePath({
  548.             method: "GET",
  549.             path: "/_matrix/app/:ver/thirdparty/user",
  550.             handler: function(req, res) {
  551.                 if (req.params.ver !== "unstable") {
  552.                     res.status(404).json(
  553.                         {err: "Unrecognised API version " + req.params.ver}
  554.                     );
  555.                     return;
  556.                 }
  558.                 var userid = req.query.userid;
  559.                 if (!userid) {
  560.                     res.status(400).send({err: "Missing 'userid' parameter"});
  561.                     return;
  562.                 }
  564.                 parseUserFunc(userid).then(
  565.                     function(result) { res.status(200).json(result) },
  566.                     function(e) { _respondErr(e, res) }
  567.                 );
  568.             },
  569.         });
  570.     }
  571. };
  573. /**
  574.  * Install a custom handler for an incoming HTTP API request. This allows
  575.  * callers to add extra functionality, implement new APIs, etc...
  576.  * @param {Object} opts Named options
  577.  * @param {string} opts.method The HTTP method name.
  578.  * @param {string} opts.path Path to the endpoint.
  579.  * @param {Bridge~appServicePathHandler} opts.handler Function to handle requests
  580.  * to this endpoint.
  581.  */
  582. Bridge.prototype.addAppServicePath = function(opts) {
  583.     // TODO(paul): This is gut-wrenching into the AppService instance itself.
  584.     //   Maybe an API on that object would be good?
  585.     var app = this.appService.app;
  587.     // TODO(paul): Consider more options:
  588.     //   opts.versions - automatic version filtering and rejecting of
  589.     //     unrecognised API versions
  590.     // Consider automatic "/_matrix/app/:version" path prefix
  592.     app[opts.method.toLowerCase()](opts.path, opts.handler);
  593. };
  595. /**
  596.  * Retrieve the connected room store instance.
  597.  * @return {?RoomBridgeStore} The connected instance ready for querying.
  598.  */
  599. Bridge.prototype.getRoomStore = function() {
  600.     return this._roomStore;
  601. };
  603. /**
  604.  * Retrieve the connected user store instance.
  605.  * @return {?UserBridgeStore} The connected instance ready for querying.
  606.  */
  607. Bridge.prototype.getUserStore = function() {
  608.     return this._userStore;
  609. };
  611. /**
  612.  * Retrieve the connected event store instance, if one was configured.
  613.  * @return {?EventBridgeStore} The connected instance ready for querying.
  614.  */
  615. Bridge.prototype.getEventStore = function() {
  616.     return this._eventStore;
  617. };
  619. /**
  620.  * Retrieve the request factory used to create incoming requests.
  621.  * @return {RequestFactory}
  622.  */
  623. Bridge.prototype.getRequestFactory = function() {
  624.     return this._requestFactory;
  625. };
  627. /**
  628.  * Retrieve the matrix client factory used when sending matrix requests.
  629.  * @return {ClientFactory}
  630.  */
  631. Bridge.prototype.getClientFactory = function() {
  632.     return this._clientFactory;
  633. };
  635. /**
  636.  * Get the AS bot instance.
  637.  * @return {AppServiceBot}
  638.  */
  639. Bridge.prototype.getBot = function() {
  640.     return this._appServiceBot;
  641. };
  643. /**
  644.  * Determines whether a room should be provisoned based on
  645.  * user provided rules and the room state. Will default to true
  646.  * if no rules have been provided.
  647.  * @param {string} roomId The room to check.
  648.  * @param {boolean} cache Should the validator check it's cache.
  649.  * @returns {Promise} resolves if can and rejects if it cannot.
  650.  *                    A status code is returned on both.
  651.  */
  652. Bridge.prototype.canProvisionRoom = function(roomId, cache=true) {
  653.     if (this._roomLinkValidator === null) {
  654.         return Promise.resolve(RLVStatus.PASSED);
  655.     }
  656.     return this._roomLinkValidator.validateRoom(roomId, cache);
  657. }
  659. Bridge.prototype.getRoomLinkValidator = function() {
  660.     return this._roomLinkValidator;
  661. }
  663. /**
  664.  * Retrieve an Intent instance for the specified user ID. If no ID is given, an
  665.  * instance for the bot itself is returned.
  666.  * @param {?string} userId The user ID to get an Intent for.
  667.  * @param {Request=} request Optional. The request instance to tie the MatrixClient
  668.  * instance to. Useful for logging contextual request IDs.
  669.  * @return {Intent} The intent instance
  670.  */
  671. Bridge.prototype.getIntent = function(userId, request) {
  672.     if (!userId) {
  673.         return this._botIntent;
  674.     }
  675.     if (this.opts.escapeUserIds === undefined || this.opts.escapeUserIds) {
  676.         userId = new MatrixUser(userId).getId(); // Escape the ID
  677.     }
  678.     const key = userId + (request ? request.getId() : "");
  679.     if (!this._intents[key]) {
  680.         const client = this._clientFactory.getClientAs(userId, request);
  681.         const clientIntentOpts = {
  682.             backingStore: this._intentBackingStore
  683.         };
  684.         if (this.opts.intentOptions.clients) {
  685.             Object.keys(this.opts.intentOptions.clients).forEach((k) => {
  686.                 clientIntentOpts[k] = this.opts.intentOptions.clients[k];
  687.             });
  688.         }
  689.         clientIntentOpts.registered = this._membershipCache.isUserRegistered(userId);
  690.         this._intents[key] = new Intent(client, this._botClient, clientIntentOpts);
  691.     }
  692.     this._intentLastAccessed[key] = Date.now();
  693.     return this._intents[key];
  694. };
  696. /**
  697.  * Retrieve an Intent instance for the specified user ID localpart. This <i>must
  698.  * be the complete user localpart</i>.
  699.  * @param {?string} localpart The user ID localpart to get an Intent for.
  700.  * @param {Request=} request Optional. The request instance to tie the MatrixClient
  701.  * instance to. Useful for logging contextual request IDs.
  702.  * @return {Intent} The intent instance
  703.  */
  704. Bridge.prototype.getIntentFromLocalpart = function(localpart, request) {
  705.     return this.getIntent(
  706.         "@" + localpart + ":" + this.opts.domain
  707.     );
  708. };
  710. /**
  711.  * Provision a user on the homeserver.
  712.  * @param {MatrixUser} matrixUser The virtual user to be provisioned.
  713.  * @param {Bridge~ProvisionedUser} provisionedUser Provisioning information.
  714.  * @return {Promise} Resolved when provisioned.
  715.  */
  716. Bridge.prototype.provisionUser = function (matrixUser, provisionedUser) {
  717.     // For backwards compat
  718.     return Promise.cast(this._provisionUser(matrixUser, provisionedUser));
  719. };
  721. Bridge.prototype._provisionUser = async function(matrixUser, provisionedUser) {
  722.     await this._botClient.register(matrixUser.localpart);
  724.     if (!this.disableStores) {
  725.         await this._userStore.setMatrixUser(matrixUser);
  726.         if (provisionedUser.remote) {
  727.             await this._userStore.linkUsers(matrixUser, provisionedUser.remote);
  728.         }
  729.     }
  730.     const userClient = this._clientFactory.getClientAs(matrixUser.getId());
  731.     if (provisionedUser.name) {
  732.         await userClient.setDisplayName(provisionedUser.name);
  733.     }
  734.     if (provisionedUser.url) {
  735.         await userClient.setAvatarUrl(provisionedUser.url);
  736.     }
  737. };
  739. Bridge.prototype._onUserQuery = async function(userId) {
  740.     if (!this.opts.controller.onUserQuery) {
  741.         return;
  742.     }
  743.     const matrixUser = new MatrixUser(userId);
  744.     try {
  745.         const provisionedUser = await this.opts.controller.onUserQuery(matrixUser);
  746.         if (!provisionedUser) {
  747.             log.warn(`Not provisioning user for ${userId}`);
  748.             return;
  749.         }
  750.         await this.provisionUser(matrixUser, provisionedUser);
  751.     }
  752.     catch (ex) {
  753.         log.error(`Failed _onUserQuery for ${userId}`, ex);
  754.     }
  755. };
  757. Bridge.prototype._onAliasQuery = function (alias) {
  758.     // For backwards compat
  759.     return Promise.cast(this.__onAliasQuery(alias));
  760. };
  762. Bridge.prototype.__onAliasQuery = async function(alias) {
  763.     if (!this.opts.controller.onAliasQuery) {
  764.         return;
  765.     }
  766.     const aliasLocalpart = alias.split(":")[0].substring(1);
  767.     const provisionedRoom = await this.opts.controller.onAliasQuery(alias, aliasLocalpart);
  768.     if (!provisionedRoom) {
  769.         throw new Error("Not provisioning room for this alias");
  770.     }
  771.     const createRoomResponse = await this._botClient.createRoom(
  772.         provisionedRoom.creationOpts
  773.     );
  774.     const roomId = createRoomResponse.room_id;
  775.     if (!this.opts.disableStores) {
  776.         const matrixRoom = new MatrixRoom(roomId);
  777.         const remoteRoom = provisionedRoom.remote;
  778.         if (remoteRoom) {
  779.             await this._roomStore.linkRooms(matrixRoom, remoteRoom);
  780.         }
  781.         else {
  782.             // store the matrix room only
  783.             await this._roomStore.setMatrixRoom(matrixRoom);
  784.         }
  785.     }
  786.     if (this.opts.controller.onAliasQueried) {
  787.         await this.opts.controller.onAliasQueried(alias, roomId);
  788.     }
  789. }
  791. Bridge.prototype._onEvent = function (event) {
  792.     return Promise.cast(this.__onEvent(event));
  793. };
  795. // returns a Promise for the request linked to this event for testing.
  796. Bridge.prototype.__onEvent = async function(event) {
  797.     const isCanonicalState = event.state_key === "";
  798.     this._updateIntents(event);
  799.     if (this.opts.suppressEcho &&
  800.             this.opts.registration.isUserMatch(event.user_id, true)) {
  801.         return null;
  802.     }
  804.     if (this._roomUpgradeHandler) {
  805.         // m.room.tombstone is the event that signals a room upgrade.
  806.         if (event.type === "m.room.tombstone" && isCanonicalState && this._roomUpgradeHandler) {
  807.             this._roomUpgradeHandler.onTombstone(event);
  808.             if (this.opts.roomUpgradeOpts.consumeEvent) {
  809.                 return null;
  810.             }
  811.         }
  812.         else if (event.type === "m.room.member" &&
  813.                 event.state_key === this._appServiceBot.getUserId() &&
  814.                 event.content.membership === "invite") {
  815.             // A invite-only room that has been upgraded won't have been joinable,
  816.             // so we are listening for any invites to the new room.
  817.             const isUpgradeInvite = this._roomUpgradeHandler.onInvite(event);
  818.             if (isUpgradeInvite &&
  819.                 this.opts.roomUpgradeOpts.consumeEvent) {
  820.                 return null;
  821.             }
  822.         }
  823.     }
  825.     const request = this._requestFactory.newRequest({ data: event });
  826.     const contextReady = this._getBridgeContext(event);
  827.     const dataReady = contextReady.then(context => ({ request, context }));
  829.     const dataReadyLimited = this._limited(dataReady, request);
  831.     this._queue.push(event, dataReadyLimited);
  832.     this._queue.consume();
  833.     const reqPromise = request.getPromise();
  835.     // We *must* return the result of the request.
  836.     return reqPromise.catch(
  837.         EventNotHandledError,
  838.         e => {
  839.             this._handleEventError(event, e)
  840.         }
  841.     );
  842. };
  844. /**
  845.  * Restricts the promise according to the bridges `perRequest` setting.
  846.  *
  847.  * `perRequest` enabled:
  848.  *     Returns a promise similar to `promise`, with the addition of it only
  849.  *     resolving after `request`.
  850.  * `perRequest` disabled:
  851.  *     Returns the promise unchanged.
  852.  */
  853. Bridge.prototype._limited = async function(promise, request) {
  854.     // queue.perRequest controls whether multiple request can be processed by
  855.     // the bridge at once.
  856.     if (this.opts.queue.perRequest) {
  857.         const promiseLimited = this._prevRequestPromise.reflect().return(promise);
  858.         this._prevRequestPromise = request.getPromise();
  859.         return promiseLimited;
  860.     }
  862.     return promise;
  863. }
  865. Bridge.prototype._onConsume = function(err, data) {
  866.     if (err) {
  867.         // The data for the event could not be retrieved.
  868.         this.opts.controller.onLog("onEvent failure: " + err, true);
  869.         return;
  870.     }
  872.     this.opts.controller.onEvent(data.request, data.context);
  873. };
  875. Bridge.prototype._getBridgeContext = async function(event) {
  876.     if (this.opts.disableContext) {
  877.         return null;
  878.     }
  880.     const context = new BridgeContext({
  881.         sender: event.user_id,
  882.         target: event.type === "m.room.member" ? event.state_key : null,
  883.         room: event.room_id
  884.     });
  886.     return context.get(this._roomStore, this._userStore);
  887. }
  889. Bridge.prototype._handleEventError = function(event, error) {
  890.     if (!(error instanceof EventNotHandledError)) {
  891.         error = wrap(error, InternalError);
  892.     }
  893.     // TODO[V02460@gmail.com]: Send via different means when the bridge bot is
  894.     // unavailable. _MSC2162: Signaling Errors at Bridges_ will have details on
  895.     // how this should be done.
  896.     this._botIntent.unstableSignalBridgeError(
  897.         event.room_id,
  898.         event.event_id,
  899.         this.opts.networkName,
  900.         error.reason,
  901.         this._getUserRegex(),
  902.     );
  903. };
  905. /**
  906.  * Returns a regex matching all users of the bridge.
  907.  *
  908.  * @return {string} Super regex composed of all user regexes.
  909.  */
  910. Bridge.prototype._getUserRegex = function() {
  911.     const reg = this.opts.registration;
  912.     return reg.namespaces["users"].map(o => o.regex);
  913. };
  915. Bridge.prototype._updateIntents = function(event) {
  916.     if (event.type === "m.room.member") {
  917.         this._membershipCache.setMemberEntry(
  918.             event.room_id,
  919.             event.state_key,
  920.             event.content ? event.content.membership : null
  921.         );
  922.     }
  923.     else if (event.type === "m.room.power_levels") {
  924.         this._setPowerLevelEntry(event.room_id, event.content);
  925.     }
  926. };
  928. Bridge.prototype._setPowerLevelEntry = function(roomId, content) {
  929.     this._powerLevelMap[roomId] = content;
  930. };
  932. Bridge.prototype._getPowerLevelEntry = function(roomId) {
  933.     return this._powerLevelMap[roomId];
  934. };
  936. /**
  937.  * Returns a PrometheusMetrics instance stored on the bridge, creating it first
  938.  * if required. The instance will be registered with the HTTP server so it can
  939.  * serve the "/metrics" page in the usual way.
  940.  * The instance will automatically register the Matrix SDK metrics by calling
  941.  * {PrometheusMetrics~registerMatrixSdkMetrics}.
  942.  */
  943. Bridge.prototype.getPrometheusMetrics = function() {
  944.     if (this._metrics) {
  945.         return this._metrics;
  946.     }
  948.     var metrics = this._metrics = new PrometheusMetrics();
  950.     metrics.registerMatrixSdkMetrics();
  952.     // TODO(paul): register some bridge-wide standard ones here
  954.     // In case we're called after .run()
  955.     if (this.appService) {
  956.         metrics.addAppServicePath(this);
  957.     }
  959.     return metrics;
  960. };
  962. /**
  963.  * A convenient shortcut to calling registerBridgeGauges() on the
  964.  * PrometheusMetrics instance directly. This version will supply the value of
  965.  * the matrixGhosts field if the counter function did not return it, for
  966.  * convenience.
  967.  * @param {PrometheusMetrics~BridgeGaugesCallback} counterFunc A function that
  968.  * when invoked returns the current counts of various items in the bridge.
  969.  *
  970.  * @example
  971.  * bridge.registerBridgeGauges(() => {
  972.  *     return {
  973.  *         matrixRoomConfigs: Object.keys(this.matrixRooms).length,
  974.  *         remoteRoomConfigs: Object.keys(this.remoteRooms).length,
  975.  *
  976.  *         remoteGhosts: Object.keys(this.remoteGhosts).length,
  977.  *
  978.  *         ...
  979.  *     }
  980.  * })
  981.  */
  982. Bridge.prototype.registerBridgeGauges = function(counterFunc) {
  983.     var self = this;
  985.     this.getPrometheusMetrics().registerBridgeGauges(function() {
  986.         var counts = counterFunc();
  988.         if (!("matrixGhosts" in counts)) {
  989.             counts.matrixGhosts = Object.keys(self._intents).length;
  990.         }
  992.         return counts;
  993.     });
  994. };
  996. Bridge.prototype._requestCheckToken = function(req, res) {
  997.     if (req.query.access_token !== this.opts.registration.hs_token) {
  998.         res.status(403).send({
  999.             errcode: "M_FORBIDDEN",
  1000.             error: "Bad token supplied,"
  1001.         });
  1002.         return false;
  1003.     }
  1004.     return true;
  1005. }
  1007. function loadDatabase(path, Cls) {
  1008.     var defer = Promise.defer();
  1009.     var db = new Datastore({
  1010.         filename: path,
  1011.         autoload: true,
  1012.         onload: function(err) {
  1013.             if (err) {
  1014.                 defer.reject(err);
  1015.             }
  1016.             else {
  1017.                 defer.resolve(new Cls(db));
  1018.             }
  1019.         }
  1020.     });
  1021.     return defer.promise;
  1022. }
  1024. function retryAlgorithm(event, attempts, err) {
  1025.     if (err.httpStatus === 400 || err.httpStatus === 403 || err.httpStatus === 401) {
  1026.         // client error; no amount of retrying with save you now.
  1027.         return -1;
  1028.     }
  1029.     // we ship with browser-request which returns { cors: rejected } when trying
  1030.     // with no connection, so if we match that, give up since they have no conn.
  1031.     if (err.cors === "rejected") {
  1032.         return -1;
  1033.     }
  1035.     if (err.name === "M_LIMIT_EXCEEDED") {
  1036.         var waitTime = err.data.retry_after_ms;
  1037.         if (waitTime) {
  1038.             return waitTime;
  1039.         }
  1040.     }
  1041.     if (attempts > 4) {
  1042.         return -1; // give up
  1043.     }
  1044.     return 1000 + (1000 * attempts);
  1045. }
  1047. function queueAlgorithm(event) {
  1048.     if (event.getType() === "m.room.message") {
  1049.         // use a separate queue for each room ID
  1050.         return "message_" + event.getRoomId();
  1051.     }
  1052.     // allow all other events continue concurrently.
  1053.     return null;
  1054. }
  1057. module.exports = Bridge;
  1060. /**
  1061.  * @typedef Bridge~ProvisionedUser
  1062.  * @type {Object}
  1063.  * @property {string=} name The display name to set for the provisioned user.
  1064.  * @property {string=} url The avatar URL to set for the provisioned user.
  1065.  * @property {RemoteUser=} remote The remote user to link to the provisioned user.
  1066.  */
  1068. /**
  1069.  * @typedef Bridge~ProvisionedRoom
  1070.  * @type {Object}
  1071.  * @property {Object} creationOpts Room creation options to use when creating the
  1072.  * room. Required.
  1073.  * @property {RemoteRoom=} remote The remote room to link to the provisioned room.
  1074.  */
  1076. /**
  1077.  * Invoked when the bridge receives a user query from the homeserver. Supports
  1078.  * both sync return values and async return values via promises.
  1079.  * @callback Bridge~onUserQuery
  1080.  * @param {MatrixUser} matrixUser The matrix user queried. Use <code>getId()</code>
  1081.  * to get the user ID.
  1082.  * @return {?Bridge~ProvisionedUser|Promise<Bridge~ProvisionedUser, Error>}
  1083.  * Reject the promise / return null to not provision the user. Resolve the
  1084.  * promise / return a {@link Bridge~ProvisionedUser} object to provision the user.
  1085.  * @example
  1086.  * new Bridge({
  1087.  *   controller: {
  1088.  *     onUserQuery: function(matrixUser) {
  1089.  *       var remoteUser = new RemoteUser("some_remote_id");
  1090.  *       return {
  1091.  *         name: matrixUser.localpart + " (Bridged)",
  1092.  *         url: "http://someurl.com/pic.jpg",
  1093.  *         user: remoteUser
  1094.  *       };
  1095.  *     }
  1096.  *   }
  1097.  * });
  1098.  */
  1100. /**
  1101.  * Invoked when the bridge receives an alias query from the homeserver. Supports
  1102.  * both sync return values and async return values via promises.
  1103.  * @callback Bridge~onAliasQuery
  1104.  * @param {string} alias The alias queried.
  1105.  * @param {string} aliasLocalpart The parsed localpart of the alias.
  1106.  * @return {?Bridge~ProvisionedRoom|Promise<Bridge~ProvisionedRoom, Error>}
  1107.  * Reject the promise / return null to not provision the room. Resolve the
  1108.  * promise / return a {@link Bridge~ProvisionedRoom} object to provision the room.
  1109.  * @example
  1110.  * new Bridge({
  1111.  *   controller: {
  1112.  *     onAliasQuery: function(alias, aliasLocalpart) {
  1113.  *       return {
  1114.  *         creationOpts: {
  1115.  *           room_alias_name: aliasLocalpart, // IMPORTANT: must be set to make the link
  1116.  *           name: aliasLocalpart,
  1117.  *           topic: "Auto-generated bridged room"
  1118.  *         }
  1119.  *       };
  1120.  *     }
  1121.  *   }
  1122.  * });
  1123.  */
  1125.  /**
  1126.   * Invoked when a response is returned from onAliasQuery. Supports
  1127.   * both sync return values and async return values via promises.
  1128.   * @callback Bridge~onAliasQueried
  1129.   * @param {string} alias The alias queried.
  1130.   * @param {string} roomId The parsed localpart of the alias.
  1131.   */
  1134.  /**
  1135.   * @callback Bridge~onRoomUpgrade
  1136.   * @param {string} oldRoomId The roomId of the old room.
  1137.   * @param {string} newRoomId The roomId of the new room.
  1138.   * @param {string} newVersion The new room version.
  1139.   * @param {Bridge~BridgeContext} context Context for the upgrade event.
  1140.   */
  1142.  /**
  1143.  * Invoked when the bridge receives an event from the homeserver.
  1144.  * @callback Bridge~onEvent
  1145.  * @param {Request} request The request to resolve or reject depending on the
  1146.  * outcome of this request. The 'data' attached to this Request is the raw event
  1147.  * JSON received (accessed via <code>request.getData()</code>)
  1148.  * @param {Bridge~BridgeContext} context Context for this event, including
  1149.  * instantiated client instances.
  1150.  */
  1152.  /**
  1153.  * Invoked when the bridge is attempting to log something.
  1154.  * @callback Bridge~onLog
  1155.  * @param {string} line The text to be logged.
  1156.  * @param {boolean} isError True if this line should be treated as an error msg.
  1157.  */
  1159.  /**
  1160.   * Handler function for custom applied HTTP API request paths. This is invoked
  1161.   * as defined by expressjs.
  1162.   * @callback Bridge~appServicePathHandler
  1163.   * @param {Request} req An expressjs Request object the handler can use to
  1164.   * inspect the incoming request.
  1165.   * @param {Response} res An expressjs Response object the handler can use to
  1166.   * send the outgoing response.
  1167.   */
  1169.  /**
  1170.   * @typedef Bridge~thirdPartyLookup
  1171.   * @type {Object}
  1172.   * @property {string[]} protocols Optional list of recognised protocol names.
  1173.   * If present, lookups for unrecognised protocols will be automatically
  1174.   * rejected.
  1175.   * @property {Bridge~getProtocol} getProtocol Function. Called for requests
  1176.   * for 3PE query metadata.
  1177.   * @property {Bridge~getLocation} getLocation Function. Called for requests
  1178.   * for 3PLs.
  1179.   * @property {Bridge~parseLocation} parseLocation Function. Called for reverse
  1180.   * parse requests on 3PL aliases.
  1181.   * @property {Bridge~getUser} getUser Function. Called for requests for 3PUs.
  1182.   * @property {Bridge~parseUser} parseUser Function. Called for reverse parse
  1183.   * requests on 3PU user IDs.
  1184.   */
  1186.  /**
  1187.   * Invoked on requests for 3PE query metadata
  1188.   * @callback Bridge~getProtocol
  1189.   * @param {string} protocol The name of the 3PE protocol to query
  1190.   * @return {Promise<Bridge~thirdPartyProtocolResult>} A Promise of metadata
  1191.   * about 3PE queries that can be made for this protocol.
  1192.   */
  1194.  /**
  1195.   * Returned by getProtocol third-party query metadata requests
  1196.   * @typedef Bridge~thirdPartyProtocolResult
  1197.   * @type {Object}
  1198.   * @property {string[]} [location_fields] Names of the fields required for
  1199.   * location lookups if location queries are supported.
  1200.   * @property {string[]} [user_fields] Names of the fields required for user
  1201.   * lookups if user queries are supported.
  1203.  /**
  1204.   * Invoked on requests for 3PLs
  1205.   * @callback Bridge~getLocation
  1206.   * @param {string} protocol The name of the 3PE protocol
  1207.   * @param {Object} fields The location query field data as specified by the
  1208.   * specific protocol.
  1209.   * @return {Promise<Bridge~thirdPartyLocationResult[]>} A Promise of a list of
  1210.   * 3PL lookup results.
  1211.   */
  1213.  /**
  1214.   * Invoked on requests to parse 3PL aliases
  1215.   * @callback Bridge~parseLocation
  1216.   * @param {string} alias The room alias to parse.
  1217.   * @return {Promise<Bridge~thirdPartyLocationResult[]>} A Promise of a list of
  1218.   * 3PL lookup results.
  1219.   */
  1221.  /**
  1222.   * Returned by getLocation and parseLocation third-party location lookups
  1223.   * @typedef Bridge~thirdPartyLocationResult
  1224.   * @type {Object}
  1225.   * @property {string} alias The Matrix room alias to the portal room
  1226.   * representing this 3PL
  1227.   * @property {string} protocol The name of the 3PE protocol
  1228.   * @property {object} fields The normalised values of the location query field
  1229.   * data.
  1230.   */
  1232.  /**
  1233.   * Invoked on requests for 3PUs
  1234.   * @callback Bridge~getUser
  1235.   * @param {string} protocol The name of the 3PE protocol
  1236.   * @param {Object} fields The user query field data as specified by the
  1237.   * specific protocol.
  1238.   * @return {Promise<Bridge~thirdPartyUserResult[]>} A Promise of a list of 3PU
  1239.   * lookup results.
  1240.   */
  1242.  /**
  1243.   * Invoked on requests to parse 3PU user IDs
  1244.   * @callback Bridge~parseUser
  1245.   * @param {string} userid The user ID to parse.
  1246.   * @return {Promise<Bridge~thirdPartyUserResult[]>} A Promise of a list of 3PU
  1247.   * lookup results.
  1248.   */
  1250.  /**
  1251.   * Returned by getUser and parseUser third-party user lookups
  1252.   * @typedef Bridge~thirdPartyUserResult
  1253.   * @type {Object}
  1254.   * @property {string} userid The Matrix user ID for the ghost representing
  1255.   * this 3PU
  1256.   * @property {string} protocol The name of the 3PE protocol
  1257.   * @property {object} fields The normalised values of the user query field
  1258.   * data.
  1259.   */