Class: Bridge

Bridge(opts)

new Bridge(opts)

Parameters:
Name Type Description
opts Object Options to pass to the bridge
Properties
Name Type Attributes Description
registration AppServiceRegistration | string Application service registration object or path to the registration file.
homeserverUrl string The base HS url
domain string The domain part for user_ids and room aliases e.g. "bar" in "@foo:bar".
controller Object The controller logic for the bridge.
Properties
Name Type Attributes Description
onEvent Bridge~onEvent Function. Called when an event has been received from the HS.
onUserQuery Bridge~onUserQuery <optional>
 Function. If supplied, the bridge will invoke this function when queried via onUserQuery. If not supplied, no users will be provisioned on user queries. Provisioned users will automatically be stored in the associated userStore.
onAliasQuery Bridge~onAliasQuery <optional>
 Function. If supplied, the bridge will invoke this function when queried via onAliasQuery. If not supplied, no rooms will be provisioned on alias queries. Provisioned rooms will automatically be stored in the associated roomStore.
onAliasQueried Bridge~onAliasQueried <optional>
 Function. If supplied, the bridge will invoke this function when a room has been created via onAliasQuery.
onLog Bridge~onLog <optional>
 Function. Invoked when logging. Defaults to a function which logs to the console.
thirdPartyLookup Bridge~thirdPartyLookup <optional>
 Object. If supplied, the bridge will respond to third-party entity lookups using the contained helper functions.
roomStore RoomBridgeStore | string <optional>
 The room store instance to use, or the path to the room .db file to load. A database will be created if this is not specified.
userStore UserBridgeStore | string <optional>
 The user store instance to use, or the path to the user .db file to load. A database will be created if this is not specified.
membershipCache MembershipCache <optional>
 The membership cache instance to use, which can be manually created by a bridge for greater control over caching. By default a membership cache will be created internally.
suppressEcho boolean <optional>
 True to stop receiving onEvent callbacks for events which were sent by a bridge user. Default: true.
clientFactory ClientFactory <optional>
 The client factory instance to use. If not supplied, one will be created.
logRequestOutcome boolean True to enable SUCCESS/FAILED log lines to be sent to onLog. Default: true.
intentOptions Object <optional>
 Options to supply to created Intent instances.
Properties
Name Type Attributes Description
bot Object <optional>
 Options to supply to the bot intent.
clients Object <optional>
 Options to supply to the client intents.
queue Object <optional>
 Options for the onEvent queue. When the bridge receives an incoming transaction, it needs to asyncly query the data store for contextual info before calling onEvent. A queue is used to keep the onEvent calls consistent with the arrival order from the incoming transactions.
Properties
Name Type Attributes Description
type string <optional>
 The type of queue to use when feeding through to Bridge~onEvent. One of: "none", single", "per_room". If "none", events are fed through as soon as contextual info is obtained, which may result in out of order events but stops HOL blocking. If "single", onEvent calls will be in order but may be slower due to HOL blocking. If "per_room", a queue per room ID is made which reduces the impact of HOL blocking to be scoped to a room. Default: "single".
perRequest boolean <optional>
 True to only feed through the next event after the request object in the previous call succeeds or fails. It is vital that you consistently resolve/reject the request if this is 'true', else you will not get any further events from this queue. To aid debugging this, consider setting a delayed listener on the request factory. If false, the mere invockation of onEvent is enough to trigger the next event in the queue. You probably want to set this to 'true' if your Bridge~onEvent is performing async operations where ordering matters (e.g. messages). Default: false.
disableContext boolean <optional>
 True to disable Bridge~BridgeContext parameters in Bridge~onEvent. Disabling the context makes the bridge do fewer database lookups, but prevents there from being a context parameter. Default: false.
Source:

Methods

_customiseAppservice()

Apply any customisations required on the appService object.
Source:

addAppServicePath(opts)

Install a custom handler for an incoming HTTP API request. This allows callers to add extra functionality, implement new APIs, etc...
Parameters:
Name Type Description
opts Object Named options
Properties
Name Type Description
method string The HTTP method name.
path string Path to the endpoint.
handler Bridge~appServicePathHandler Function to handle requests to this endpoint.
Source:

getBot() → {AppServiceBot}

Get the AS bot instance.
Source:
Returns:
Type
AppServiceBot

getClientFactory() → {ClientFactory}

Retrieve the matrix client factory used when sending matrix requests.
Source:
Returns:
Type
ClientFactory

getIntent(userIdnullable, requestopt) → {Intent}

Retrieve an Intent instance for the specified user ID. If no ID is given, an instance for the bot itself is returned.
Parameters:
Name Type Attributes Description
userId string <nullable>
 The user ID to get an Intent for.
request Request <optional>
 Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.
Source:
Returns:
The intent instance
Type
Intent

getIntentFromLocalpart(localpartnullable, requestopt) → {Intent}

Retrieve an Intent instance for the specified user ID localpart. This must be the complete user localpart.
Parameters:
Name Type Attributes Description
localpart string <nullable>
 The user ID localpart to get an Intent for.
request Request <optional>
 Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.
Source:
Returns:
The intent instance
Type
Intent

getPrometheusMetrics()

Returns a PrometheusMetrics instance stored on the bridge, creating it first if required. The instance will be registered with the HTTP server so it can serve the "/metrics" page in the usual way. The instance will automatically register the Matrix SDK metrics by calling {PrometheusMetrics~registerMatrixSdkMetrics}.
Source:

getRequestFactory() → {RequestFactory}

Retrieve the request factory used to create incoming requests.
Source:
Returns:
Type
RequestFactory

getRoomStore() → (nullable) {RoomBridgeStore}

Retrieve a connected room store instance.
Source:
Returns:
The connected instance ready for querying.
Type
RoomBridgeStore

getUserStore() → (nullable) {UserBridgeStore}

Retrieve a connected user store instance.
Source:
Returns:
The connected instance ready for querying.
Type
UserBridgeStore

loadDatabases() → {Promise}

Load the user and room databases. Access them via getUserStore() and getRoomStore().
Source:
Returns:
Resolved/rejected when the user/room databases have been loaded.
Type
Promise

provisionUser(matrixUser, provisionedUser) → {Promise}

Provision a user on the homeserver.
Parameters:
Name Type Description
matrixUser MatrixUser The virtual user to be provisioned.
provisionedUser Bridge~ProvisionedUser Provisioning information.
Source:
Returns:
Resolved when provisioned.
Type
Promise

registerBridgeGauges(counterFunc)

A convenient shortcut to calling registerBridgeGauges() on the PrometheusMetrics instance directly. This version will supply the value of the matrixGhosts field if the counter function did not return it, for convenience.
Parameters:
Name Type Description
counterFunc PrometheusMetrics~BridgeGaugesCallback A function that when invoked returns the current counts of various items in the bridge.
Source:
Example
bridge.registerBridgeGauges(() => {
    return {
        matrixRoomConfigs: Object.keys(this.matrixRooms).length,
        remoteRoomConfigs: Object.keys(this.remoteRooms).length,

        remoteGhosts: Object.keys(this.remoteGhosts).length,

        ...
    }
})

run(port, config, appServiceInstanceopt)

Run the bridge (start listening)
Parameters:
Name Type Attributes Description
port Number The port to listen on.
config Object Configuration options
appServiceInstance AppService <optional>
 The AppService instance to attach to. If not provided, one will be created.
Source:

Type Definitions

appServicePathHandler(req, res)

Handler function for custom applied HTTP API request paths. This is invoked as defined by expressjs.
Parameters:
Name Type Description
req Request An expressjs Request object the handler can use to inspect the incoming request.
res Response An expressjs Response object the handler can use to send the outgoing response.
Source:

BridgeContext

Type:
  • Object
Properties:
Name Type Description
senders Object Data models on senders of this event
Properties
Name Type Attributes Description
matrix MatrixUser The sender of this event
remote RemoteUser <nullable>
 The first linked remote sender: remotes[0]
remotes Array.<RemoteUser> The linked remote senders
targets Object Data models on targets (e.g. state_key in m.room.member) of this event.
Properties
Name Type Attributes Description
matrix MatrixUser <nullable>
 The target of this event if applicable.
remote RemoteUser <nullable>
 The first linked remote target: remotes[0]
remotes Array.<RemoteUser> The linked remote targets
rooms Object Data models on rooms concerning this event.
Properties
Name Type Attributes Description
matrix MatrixRoom The room for this event.
remote RemoteRoom <nullable>
 The first linked remote room: remotes[0]
remotes Array.<RemoteRoom> The linked remote rooms for this event
Source:

getLocation(protocol, fields) → {Promise.<Array.<Bridge~thirdPartyLocationResult>>}

Returned by getProtocol third-party query metadata requests
Parameters:
Name Type Description
protocol string The name of the 3PE protocol
fields Object The location query field data as specified by the specific protocol.
Properties:
Name Type Attributes Description
location_fields Array.<string> <optional>
 Names of the fields required for location lookups if location queries are supported.
user_fields Array.<string> <optional>
 Names of the fields required for user lookups if user queries are supported. /** Invoked on requests for 3PLs
Source:
Returns:
A Promise of a list of 3PL lookup results.
Type
Promise.<Array.<Bridge~thirdPartyLocationResult>>

getProtocol(protocol) → {Promise.<Bridge~thirdPartyProtocolResult>}

Invoked on requests for 3PE query metadata
Parameters:
Name Type Description
protocol string The name of the 3PE protocol to query
Source:
Returns:
A Promise of metadata about 3PE queries that can be made for this protocol.
Type
Promise.<Bridge~thirdPartyProtocolResult>

getUser(protocol, fields) → {Promise.<Array.<Bridge~thirdPartyUserResult>>}

Invoked on requests for 3PUs
Parameters:
Name Type Description
protocol string The name of the 3PE protocol
fields Object The user query field data as specified by the specific protocol.
Source:
Returns:
A Promise of a list of 3PU lookup results.
Type
Promise.<Array.<Bridge~thirdPartyUserResult>>

onAliasQueried(alias, roomId)

Invoked when a response is returned from onAliasQuery. Supports both sync return values and async return values via promises.
Parameters:
Name Type Description
alias string The alias queried.
roomId string The parsed localpart of the alias.
Source:

onAliasQuery(alias, aliasLocalpart) → {Bridge~ProvisionedRoom|Promise.<Bridge~ProvisionedRoom, Error>}

Invoked when the bridge receives an alias query from the homeserver. Supports both sync return values and async return values via promises.
Parameters:
Name Type Description
alias string The alias queried.
aliasLocalpart string The parsed localpart of the alias.
Source:
Returns:
Reject the promise / return null to not provision the room. Resolve the promise / return a Bridge~ProvisionedRoom object to provision the room.
Type
Bridge~ProvisionedRoom | Promise.<Bridge~ProvisionedRoom, Error>
Example
new Bridge({
  controller: {
    onAliasQuery: function(alias, aliasLocalpart) {
      return {
        creationOpts: {
          room_alias_name: aliasLocalpart, // IMPORTANT: must be set to make the link
          name: aliasLocalpart,
          topic: "Auto-generated bridged room"
        }
      };
    }
  }
});

onEvent(request, context)

Invoked when the bridge receives an event from the homeserver.
Parameters:
Name Type Description
request Request The request to resolve or reject depending on the outcome of this request. The 'data' attached to this Request is the raw event JSON received (accessed via request.getData())
context Bridge~BridgeContext Context for this event, including instantiated client instances.
Source:

onLog(line, isError)

Invoked when the bridge is attempting to log something.
Parameters:
Name Type Description
line string The text to be logged.
isError boolean True if this line should be treated as an error msg.
Source:

onUserQuery(matrixUser) → {Bridge~ProvisionedUser|Promise.<Bridge~ProvisionedUser, Error>}

Invoked when the bridge receives a user query from the homeserver. Supports both sync return values and async return values via promises.
Parameters:
Name Type Description
matrixUser MatrixUser The matrix user queried. Use getId() to get the user ID.
Source:
Returns:
Reject the promise / return null to not provision the user. Resolve the promise / return a Bridge~ProvisionedUser object to provision the user.
Type
Bridge~ProvisionedUser | Promise.<Bridge~ProvisionedUser, Error>
Example
new Bridge({
  controller: {
    onUserQuery: function(matrixUser) {
      var remoteUser = new RemoteUser("some_remote_id");
      return {
        name: matrixUser.localpart + " (Bridged)",
        url: "http://someurl.com/pic.jpg",
        user: remoteUser
      };
    }
  }
});

parseLocation(alias) → {Promise.<Array.<Bridge~thirdPartyLocationResult>>}

Invoked on requests to parse 3PL aliases
Parameters:
Name Type Description
alias string The room alias to parse.
Source:
Returns:
A Promise of a list of 3PL lookup results.
Type
Promise.<Array.<Bridge~thirdPartyLocationResult>>

parseUser(userid) → {Promise.<Array.<Bridge~thirdPartyUserResult>>}

Invoked on requests to parse 3PU user IDs
Parameters:
Name Type Description
userid string The user ID to parse.
Source:
Returns:
A Promise of a list of 3PU lookup results.
Type
Promise.<Array.<Bridge~thirdPartyUserResult>>

ProvisionedRoom

Type:
  • Object
Properties:
Name Type Attributes Description
creationOpts Object Room creation options to use when creating the room. Required.
remote RemoteRoom <optional>
 The remote room to link to the provisioned room.
Source:

ProvisionedUser

Type:
  • Object
Properties:
Name Type Attributes Description
name string <optional>
 The display name to set for the provisioned user.
url string <optional>
 The avatar URL to set for the provisioned user.
remote RemoteUser <optional>
 The remote user to link to the provisioned user.
Source:

thirdPartyLocationResult

Returned by getLocation and parseLocation third-party location lookups
Type:
  • Object
Properties:
Name Type Description
alias string The Matrix room alias to the portal room representing this 3PL
protocol string The name of the 3PE protocol
fields object The normalised values of the location query field data.
Source:

thirdPartyLookup

Type:
  • Object
Properties:
Name Type Description
protocols Array.<string> Optional list of recognised protocol names. If present, lookups for unrecognised protocols will be automatically rejected.
getProtocol Bridge~getProtocol Function. Called for requests for 3PE query metadata.
getLocation Bridge~getLocation Function. Called for requests for 3PLs.
parseLocation Bridge~parseLocation Function. Called for reverse parse requests on 3PL aliases.
getUser Bridge~getUser Function. Called for requests for 3PUs.
parseUser Bridge~parseUser Function. Called for reverse parse requests on 3PU user IDs.
Source:

thirdPartyUserResult

Returned by getUser and parseUser third-party user lookups
Type:
  • Object
Properties:
Name Type Description
userid string The Matrix user ID for the ghost representing this 3PU
protocol string The name of the 3PE protocol
fields object The normalised values of the user query field data.
Source: