mxmain

Documentation

Overview

Package mxmain contains initialization code for a single-network Matrix bridge using the bridgev2 package.

Index

• Variables
• type BridgeMain
  • func (br *BridgeMain) CheckLegacyDB(expectedVersion int, minBridgeVersion, firstMegaVersion string, ...)
  • func (br *BridgeMain) GenerateRegistration()
  • func (br *BridgeMain) Init()
  • func (br *BridgeMain) InitVersion(tag, commit, rawBuildTime string)
  • func (br *BridgeMain) LegacyMigrateSimple(renameTablesQuery, copyDataQuery string, newDBVersion int) func(ctx context.Context) error
  • func (br *BridgeMain) LoadConfig()
  • func (br *BridgeMain) LogDBUpgradeErrorAndExit(name string, err error, message string)
  • func (br *BridgeMain) PreInit()
  • func (br *BridgeMain) Run()
  • func (br *BridgeMain) Start()
  • func (br *BridgeMain) Stop()
  • func (br *BridgeMain) TriggerStop(exitCode int)
  • func (br *BridgeMain) WaitForInterrupt() int
• type VersionJSONOutput

Examples

• BridgeMain

Variables

var MatrixExampleConfigBase string

Types

type BridgeMain

type BridgeMain struct {
	// Name is the name of the bridge project, e.g. mautrix-signal.
	// Note that when making your own bridges that isn't under github.com/mautrix,
	// you should invent your own name and not use the mautrix-* naming scheme.
	Name string
	// Description is a brief description of the bridge, usually of the form "A Matrix-OtherPlatform puppeting bridge."
	Description string
	// URL is the Git repository address for the bridge.
	URL string
	// Version is the latest release of the bridge. InitVersion will compare this to the provided
	// git tag to see if the built version is the release or a dev build.
	// You can either bump this right after a release or right before, as long as it matches on the release commit.
	Version string

	// PostInit is a function that will be called after the bridge has been initialized but before it is started.
	PostInit  func()
	PostStart func()

	// Connector is the network connector for the bridge.
	Connector bridgev2.NetworkConnector

	Log    *zerolog.Logger
	DB     *dbutil.Database
	Config *bridgeconfig.Config
	Matrix *matrix.Connector
	Bridge *bridgev2.Bridge

	ConfigPath       string
	RegistrationPath string
	SaveConfig       bool

	LinkifiedVersion string
	VersionDesc      string
	BuildTime        time.Time

	AdditionalShortFlags string
	AdditionalLongFlags  string
	// contains filtered or unexported fields
}

BridgeMain contains the main function for a Matrix bridge.

Example

package main

import (
	"github.com/element-hq/mautrix-go/bridgev2"
	"github.com/element-hq/mautrix-go/bridgev2/matrix/mxmain"
)

// Information to find out exactly which commit the bridge was built from.
// These are filled at build time with the -X linker flag.
var (
	Tag       = "unknown"
	Commit    = "unknown"
	BuildTime = "unknown"
)

func main() {
	// Set this yourself
	var yourConnector bridgev2.NetworkConnector

	m := mxmain.BridgeMain{
		Name:        "example-matrix-bridge",
		URL:         "https://github.com/octocat/matrix-bridge",
		Description: "An example Matrix bridge.",
		Version:     "1.0.0",

		Connector: yourConnector,
	}
	m.PostInit = func() {
		// If you want some code to run after all the setup is done, but before the bridge is started,
		// you can set a function in PostInit. This is not required if you don't need to do anything special.
	}
	m.InitVersion(Tag, Commit, BuildTime)
	m.Run()
}

func (*BridgeMain) CheckLegacyDB

func (br *BridgeMain) CheckLegacyDB(expectedVersion int, minBridgeVersion, firstMegaVersion string, migrator func(context.Context) error, transaction bool)

func (*BridgeMain) GenerateRegistration

func (br *BridgeMain) GenerateRegistration()

func (*BridgeMain) Init

func (br *BridgeMain) Init()

Init sets up logging, database connection and creates the Matrix connector and central Bridge struct. This is called by [Run] and does not need to be called manually.

func (*BridgeMain) InitVersion

func (br *BridgeMain) InitVersion(tag, commit, rawBuildTime string)

InitVersion formats the bridge version and build time nicely for things like the `version` bridge command on Matrix and the `--version` CLI flag.

The values should generally be set by the build system. For example, assuming you have

var (
	Tag       = "unknown"
	Commit    = "unknown"
	BuildTime = "unknown"
)

in your main package, then you'd use the following ldflags to fill them appropriately:

go build -ldflags "-X main.Tag=$(git describe --exact-match --tags 2>/dev/null) -X main.Commit=$(git rev-parse HEAD) -X 'main.BuildTime=`date -Iseconds`'"

You may additionally want to fill the mautrix-go version using another ldflag:

export MAUTRIX_VERSION=$(cat go.mod | grep 'github.com/element-hq/mautrix-go ' | head -n1 | awk '{ print $2 }')
go build -ldflags "-X 'github.com/element-hq/mautrix-go.GoModVersion=$MAUTRIX_VERSION'"

(to use both at the same time, simply merge the ldflags into one, `-ldflags "-X '...' -X ..."`)

func (*BridgeMain) LegacyMigrateSimple

func (br *BridgeMain) LegacyMigrateSimple(renameTablesQuery, copyDataQuery string, newDBVersion int) func(ctx context.Context) error

func (*BridgeMain) LoadConfig

func (br *BridgeMain) LoadConfig()

LoadConfig upgrades and loads the config file. This is called by [Run] and does not need to be called manually.

func (*BridgeMain) LogDBUpgradeErrorAndExit

func (br *BridgeMain) LogDBUpgradeErrorAndExit(name string, err error, message string)

func (*BridgeMain) PreInit

func (br *BridgeMain) PreInit()

PreInit parses CLI flags and loads the config file. This is called by [Run] and does not need to be called manually.

This also handles all flags that cause the bridge to exit immediately (e.g. `--version` and `--generate-registration`).

func (*BridgeMain) Run

func (br *BridgeMain) Run()

Run runs the bridge and waits for SIGTERM before stopping.

func (*BridgeMain) Start

func (br *BridgeMain) Start()

Start starts the bridge after everything has been initialized. This is called by [Run] and does not need to be called manually.

func (*BridgeMain) Stop

func (br *BridgeMain) Stop()

Stop cleanly stops the bridge. This is called by [Run] and does not need to be called manually.

func (*BridgeMain) TriggerStop

func (br *BridgeMain) TriggerStop(exitCode int)

func (*BridgeMain) WaitForInterrupt

func (br *BridgeMain) WaitForInterrupt() int

WaitForInterrupt waits for a SIGINT or SIGTERM signal.

type VersionJSONOutput

type VersionJSONOutput struct {
	Name string
	URL  string

	Version          string
	IsRelease        bool
	Commit           string
	FormattedVersion string
	BuildTime        time.Time

	OS   string
	Arch string

	Mautrix struct {
		Version string
		Commit  string
	}
}