Class Bridge

constructor

• new Bridge(opts: BridgeOpts): Bridge

  Parameters

  • opts: BridgeOpts

    Options to pass to the bridge

    • OptionalbridgeEncryption?: { homeserverUrl: string; store: ClientEncryptionStore }

    • controller: BridgeController

      The controller logic for the bridge.

    • OptionaldisableContext?: boolean

      true to disable 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.

    • OptionaldisableStores?: boolean

      True to disable enabling of stores. This should be used by bridges that use their own database instances and do not need any of the included store objects. This implies setting disableContext to True. Default: false.

    • domain: string

      The domain part for user_ids and room aliases e.g. "bar" in "@foo:bar".

    • OptionalescapeUserIds?: boolean

      Escape userIds for non-bot intents with ~escapeUserId Default: true

    • OptionaleventStore?: string | EventBridgeStore

      The event store instance to use, or the path to the user .db file to load. A database will NOT be created if this is not specified. If disableStores is set, no database will be created or used.

    • OptionaleventValidation?: { validateEditSender?: { allowEventOnLookupFail: boolean } }

      • OptionalvalidateEditSender?: { allowEventOnLookupFail: boolean }

        Should we validate that the sender of an edit matches the parent event.

        • allowEventOnLookupFail: boolean

          If the parent edit event could not be found, should the event be rejected.

    • homeserverUrl: string

      The base HS url

    • OptionalintentOptions?: { bot?: IntentOpts; clients?: IntentOpts }

      Options to supply to created Intent instances.

      • Optionalbot?: IntentOpts

        Options to supply to the bot intent.

      • Optionalclients?: IntentOpts

        Options to supply to the client intents.

    • OptionallogRequestOutcome?: boolean

      True to enable SUCCESS/FAILED log lines to be sent to onLog. Default: true.

    • OptionalmembershipCache?: MembershipCache

      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.

    • OptionalnetworkName?: string

      A human readable string that will be used when the bridge signals errors to the client. Will not include in error events if ommited.

    • OptionalonIntentCreate?: (userId: string) => Intent

      The factory function used to create intents.

    • Optionalqueue?: { perRequest?: boolean; type?: "none" | "single" | "per_room" }

      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.

      • OptionalperRequest?: boolean

        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 invocation of onEvent is enough to trigger the next event in the queue. You probably want to set this to true if your ~onEvent is performing async operations where ordering matters (e.g. messages).

        Default: false.

      • Optionaltype?: "none" | "single" | "per_room"

        The type of queue to use when feeding through to ~onEvent.

        • 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.

    • registration: string | AppServiceRegistration

      Application service registration object or path to the registration file.

    • OptionalroomLinkValidation?: { rules: Rules }

    • OptionalroomStore?: string | RoomBridgeStore

      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. If disableStores is set, no database will be created or used.

    • OptionalroomUpgradeOpts?: RoomUpgradeHandlerOpts

    • OptionalsuppressEcho?: boolean

      True to stop receiving onEvent callbacks for events which were sent by a bridge user. Default: true.

    • OptionaltrackUserActivity?: ActivityTrackerOpts

    • OptionaluserActivityStore?: string | UserActivityStore

      The user activity store instance to use, or the path to the user .db file to load. A database will be created if this is not specified. If disableStores is set, no database will be created or used.

    • OptionaluserStore?: string | UserBridgeStore

      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. If disableStores is set, no database will be created or used.

  Returns Bridge

Readonlyopts

activityTracker

• get activityTracker(): undefined | ActivityTracker

  Returns undefined | ActivityTracker

appService

• get appService(): AppService

  Returns AppService

botUserId

• get botUserId(): string

  Returns string

addAppServicePath

• addAppServicePath(
      opts: {
          authenticate?: boolean;
          handler: (req: Request, respose: Response, next: NextFunction) => void;
          method: "GET" | "POST" | "PUT" | "DELETE";
          path: string;
      },
  ): void

  Install a custom handler for an incoming HTTP API request. This allows callers to add extra functionality, implement new APIs, etc...

  Parameters

  • opts: {
        authenticate?: boolean;
        handler: (req: Request, respose: Response, next: NextFunction) => void;
        method: "GET" | "POST" | "PUT" | "DELETE";
        path: string;
    }

    Named options

    • Optionalauthenticate?: boolean

      Should the token be automatically checked. Defaults to true.

    • handler: (req: Request, respose: Response, next: NextFunction) => void

      Function to handle requests

    • method: "GET" | "POST" | "PUT" | "DELETE"

      The HTTP method name.

    • path: string

      Path to the endpoint. to this endpoint.

  Returns void

canProvisionRoom

• canProvisionRoom(
      roomId: string,
      cache?: boolean,
  ): Promise<RoomLinkValidatorStatus>

  Determines whether a room should be provisoned based on user provided rules and the room state. Will default to true if no rules have been provided.

  Parameters

  • roomId: string

    The room to check.
  • cache: boolean = true

    Should the validator check its cache.

  Returns Promise<RoomLinkValidatorStatus>

  resolves if can and rejects if it cannot. A status code is returned on both.

checkHomeserverSupport

• checkHomeserverSupport(): Promise<void>

  Returns Promise<void>

close

• close(): Promise<void>

  Close the appservice HTTP listener, and clear all timeouts.

  Returns Promise<void>

  Resolves when the appservice HTTP listener has stopped

getAnyASMemberInRoom

• getAnyASMemberInRoom(
      roomId: string,
      preferBot?: boolean,
  ): Promise<null | string>

  Find a member for a given room. This method will fetch the joined members from the homeserver if the cache doesn't have it stored.

  Parameters

  • roomId: string
  • preferBot: boolean = true

    Should we prefer the bot user over a ghost user

  Returns Promise<null | string>

  The userID of the member.

getBot

• getBot(): AppServiceBot

  Get the AS bot instance.

  Returns AppServiceBot

getEventStore

• getEventStore(): undefined | EventBridgeStore

  Retrieve the connected event store instance, if one was configured.

  Returns undefined | EventBridgeStore

getIntent

• getIntent(userId?: string, request?: Request<unknown>): Intent | EncryptedIntent

  Retrieve an Intent instance for the specified user ID. If no ID is given, an instance for the bot itself is returned.

  Parameters

  • OptionaluserId: string

    Optional. The user ID to get an Intent for.
  • Optionalrequest: Request<unknown>

    Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.

  Returns Intent | EncryptedIntent

  The intent instance

getIntentFromLocalpart

• getIntentFromLocalpart(localpart: string, request?: Request<unknown>): Intent

  Retrieve an Intent instance for the specified user ID localpart. This must be the complete user localpart.

  Parameters

  • localpart: string

    The user ID localpart to get an Intent for.
  • Optionalrequest: Request<unknown>

    Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.

  Returns Intent

  The intent instance

getPrometheusMetrics

• getPrometheusMetrics(
      registerEndpoint?: boolean,
      registry?: Registry<"text/plain; version=0.0.4; charset=utf-8">,
  ): PrometheusMetrics

  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}.

  Ensure that PackageInfo.getBridgeVersion is returns the correct version before calling this, as changes to the bridge version after metric instantiation will not be detected.

  Parameters

  • registerEndpoint: boolean = true

    Register the /metrics endpoint on the appservice HTTP server. Defaults to true. Note: listen() must have been called if this is true or this will throw.
  • Optionalregistry: Registry<"text/plain; version=0.0.4; charset=utf-8">

    Optionally provide an alternative registry for metrics.

  Returns PrometheusMetrics

getRequestFactory

• getRequestFactory(): RequestFactory

  Retrieve the request factory used to create incoming requests.

  Returns RequestFactory

getRoomLinkValidator

• getRoomLinkValidator(): undefined | RoomLinkValidator

  Returns undefined | RoomLinkValidator

getRoomStore

• getRoomStore(): undefined | RoomBridgeStore

  Retrieve the connected room store instance, if one was configured.

  Returns undefined | RoomBridgeStore

getUserActivityStore

• getUserActivityStore(): undefined | UserActivityStore

  Retrieve the connected user activity store instance.

  Returns undefined | UserActivityStore

getUserStore

• getUserStore(): undefined | UserBridgeStore

  Retrieve the connected user store instance, if one was configured.

  Returns undefined | UserBridgeStore

initialise

• initialise(): Promise<void>

  Load registration, databases and initialise bridge components.

  This must be called before listen()

  Returns Promise<void>

listen

• listen(
      port: number,
      hostname?: string,
      backlog?: number,
      appServiceInstance?: AppService,
  ): Promise<void>

  Setup a HTTP listener to handle appservice traffic. ** This must be called after .initialise() **

  Parameters

  • port: number

    The port to listen on.
  • hostname: string = "0.0.0.0"

    Optional hostname to bind to.
  • backlog: number = 10
  • OptionalappServiceInstance: AppService

    The AppService instance to attach to. If not provided, one will be created.

  Returns Promise<void>

loadDatabases

• loadDatabases(): Promise<void>

  Load the user and room databases. Access them via getUserStore() and getRoomStore().

  Returns Promise<void>

pingAppserviceRoute

• pingAppserviceRoute(roomId: string, timeoutMs?: number): Promise<number>

  Check the homeserver -> appservice connection by sending a ping event.

  Parameters

  • roomId: string

    The room to use as a ping check.
  • timeoutMs: number = BRIDGE_PING_TIMEOUT_MS

    How long to wait for the ping attempt. Defaults to 60s.

  Returns Promise<number>

  The delay in milliseconds

  Throws

  This will throw if another ping attempt is made, or if the request times out.

provisionUser

• provisionUser(
      matrixUser: MatrixUser,
      provisionedUser?: { name?: string; remote?: RemoteUser; url?: string },
  ): Promise<void>

  Provision a user on the homeserver.

  Parameters

  • matrixUser: MatrixUser

    The virtual user to be provisioned.
  • OptionalprovisionedUser: { name?: string; remote?: RemoteUser; url?: string }

    Provisioning information.

  Returns Promise<void>

  Resolved when provisioned.

registerBridgeGauges

• registerBridgeGauges(
      counterFunc: () => BridgeGaugesCounts | Promise<BridgeGaugesCounts>,
  ): void

  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

  • counterFunc: () => BridgeGaugesCounts | Promise<BridgeGaugesCounts>

    A function that when invoked returns the current counts of various items in the bridge.

  Returns void

  Example

  bridge.registerBridgeGauges(() => {
      return {
          matrixRoomConfigs: Object.keys(this.matrixRooms).length,
          remoteRoomConfigs: Object.keys(this.remoteRooms).length,
  
          remoteGhosts: Object.keys(this.remoteGhosts).length,
  
          ...
      }
  })
  Copy

requestCheckToken

• requestCheckToken(req: Request): boolean

  Check a express Request to see if it's correctly authenticated (includes the hsToken). The query parameter access_token and the Authorization header are checked.

  Parameters

  • req: Request

  Returns boolean

  True if authenticated, False if not.

run

• run(
      port: number,
      appServiceInstance?: AppService,
      hostname?: string,
      backlog?: number,
  ): Promise<void>

  Run the bridge (start listening). This calls initialise() and listen().

  Parameters

  • port: number

    The port to listen on.
  • OptionalappServiceInstance: AppService

    The AppService instance to attach to. If not provided, one will be created.
  • hostname: string = "0.0.0.0"

    Optional hostname to bind to.
  • backlog: number = 10

  Returns Promise<void>

  A promise resolving when the bridge is ready.

updateRoomLinkValidatorRules

• updateRoomLinkValidatorRules(rules: Rules): void

  Parameters

  • rules: Rules

  Returns void