Class Bridge

Hierarchy

Bridge

Constructors

constructor

new Bridge(opts: BridgeOpts): Bridge
Parameters
- opts: BridgeOpts
  
  Options to pass to the bridge
Returns Bridge

Properties

`Readonly` opts

opts: VettedBridgeOpts

Accessors

activityTracker

get activityTracker(): undefined | ActivityTracker
Returns undefined | ActivityTracker

appService

get appService(): AppService
Returns AppService

botUserId

get botUserId(): string
Returns string

Methods

addAppServicePath

addAppServicePath(opts: { authenticate?: boolean; handler: ((req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, respose: Response<any, Record<string, any>>, next: NextFunction) => void); method: "PUT" | "POST" | "GET" | "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<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, respose: Response<any, Record<string, any>>, next: NextFunction) => void); method: "PUT" | "POST" | "GET" | "DELETE"; path: string }
  
  Named options
  - Optional authenticate?: boolean
    
    Should the token be automatically checked. Defaults to true.
  - handler: ((req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, respose: Response<any, Record<string, any>>, next: NextFunction) => void)
    - (req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, respose: Response<any, Record<string, any>>, next: NextFunction): void
      
      Function to handle requests
      
      Parameters
      
      req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>
      
      respose: Response<any, Record<string, any>>
      
      next: NextFunction
      
      Returns void
  - method: "PUT" | "POST" | "GET" | "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.

Returns
resolves if can and rejects if it cannot. A status code is returned on both.
Parameters
- roomId: string
  
  The room to check.
- cache: boolean = true
  
  Should the validator check its cache.
Returns Promise<RoomLinkValidatorStatus>

checkHomeserverSupport

checkHomeserverSupport(): Promise<void>
Returns Promise<void>

close

close(): Promise<void>
Close the appservice HTTP listener, and clear all timeouts.

Returns
Resolves when the appservice HTTP listener has stopped

Returns Promise<void>

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.

Returns
The userID of the member.
Parameters
- roomId: string
- preferBot: boolean = true
  
  Should we prefer the bot user over a ghost user
Returns Promise<null | string>

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.

Returns
The intent instance
Parameters
- Optional userId: string
  
  Optional. The user ID to get an Intent for.
- Optional request: Request<unknown>
  
  Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.
Returns Intent | EncryptedIntent

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.

Returns
The intent instance
Parameters
- localpart: string
  
  The user ID localpart to get an Intent for.
- Optional request: Request<unknown>
  
  Optional. The request instance to tie the MatrixClient instance to. Useful for logging contextual request IDs.
Returns Intent

getPrometheusMetrics

getPrometheusMetrics(registerEndpoint?: boolean, registry?: Registry): 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.
- Optional registry: Registry
  
  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

initalise

initalise(): Promise<void>
Load registration, databases and initalise 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 .initalise() **
Parameters
- port: number
  
  The port to listen on.
- hostname: string = "0.0.0.0"
  
  Optional hostname to bind to.
- backlog: number = 10
- Optional appServiceInstance: 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.

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

Returns
The delay in milliseconds
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>

provisionUser

provisionUser(matrixUser: MatrixUser, provisionedUser?: { name?: string; remote?: RemoteUser; url?: string }): Promise<void>
Provision a user on the homeserver.

Returns
Resolved when provisioned.
Parameters
- matrixUser: MatrixUser
  
  The virtual user to be provisioned.
- Optional provisionedUser: { name?: string; remote?: RemoteUser; url?: string }
  
  Provisioning information.
  - Optional name?: string
  - Optional remote?: RemoteUser
  - Optional url?: string
Returns Promise<void>

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.

Example
```
bridge.registerBridgeGauges(() => {
    return {
        matrixRoomConfigs: Object.keys(this.matrixRooms).length,
        remoteRoomConfigs: Object.keys(this.remoteRooms).length,

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

        ...
    }
})
```
Parameters
- counterFunc: (() => BridgeGaugesCounts | Promise<BridgeGaugesCounts>)
  
  A function that when invoked returns the current counts of various items in the bridge.
  - - (): BridgeGaugesCounts | Promise<BridgeGaugesCounts>
    - Returns BridgeGaugesCounts | Promise<BridgeGaugesCounts>
Returns void

requestCheckToken

requestCheckToken(req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>): 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.

Returns
True if authenticated, False if not.
Parameters
- req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>
Returns boolean

run

run(port: number, appServiceInstance?: AppService, hostname?: string, backlog?: number): Promise<void>
Run the bridge (start listening). This calls initalise() and listen().

Returns
A promise resolving when the bridge is ready.
Parameters
- port: number
  
  The port to listen on.
- Optional appServiceInstance: 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>

updateRoomLinkValidatorRules

updateRoomLinkValidatorRules(rules: Rules): void
Parameters
- rules: Rules
Returns void

Class Bridge

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

opts: BridgeOpts

Returns Bridge

Properties

Readonly opts

Accessors

activityTracker

Returns undefined | ActivityTracker

appService

Returns AppService

botUserId

Returns string

Methods

addAppServicePath

Parameters

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

Optional authenticate?: boolean

handler: ((req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>, respose: Response<any, Record<string, any>>, next: NextFunction) => void)

Parameters

req: Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>

respose: Response<any, Record<string, any>>

next: NextFunction

Returns void

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

path: string

Returns void

canProvisionRoom

Returns

Parameters

roomId: string

cache: boolean = true

Returns Promise<RoomLinkValidatorStatus>

checkHomeserverSupport

Returns Promise<void>

close

Returns

Returns Promise<void>

getAnyASMemberInRoom

Returns

Parameters

roomId: string

preferBot: boolean = true

Returns Promise<null | string>

getBot

Returns AppServiceBot

getEventStore

Returns undefined | EventBridgeStore

getIntent

Returns

Parameters

Optional userId: string

Optional request: Request<unknown>

Returns Intent | EncryptedIntent

getIntentFromLocalpart

Returns

Parameters

localpart: string

Optional request: Request<unknown>

Returns Intent

getPrometheusMetrics

Parameters

registerEndpoint: boolean = true

Optional registry: Registry

Returns PrometheusMetrics

getRequestFactory

Returns RequestFactory

getRoomLinkValidator

Returns undefined | RoomLinkValidator

getRoomStore

Returns undefined | RoomBridgeStore

getUserActivityStore

`Readonly` opts

`Optional` authenticate?: boolean

`Optional` userId: string

`Optional` request: Request<unknown>

`Optional` request: Request<unknown>

`Optional` registry: Registry

`Optional` appServiceInstance: AppService

`Optional` provisionedUser: { name?: string; remote?: RemoteUser; url?: string }

`Optional` name?: string

`Optional` remote?: RemoteUser

`Optional` url?: string

`Optional` appServiceInstance: AppService