matrix

Documentation

Overview

Package matrix is a Matrix chat frontend for mezzaops, parallel to the Mattermost and Discord frontends. It listens for command-prefixed messages in one configured room, dispatches them to the service manager, and posts notifications to the same room. End-to-end encryption is handled transparently by mautrix's cryptohelper using an on-disk SQLite store.

Index

• type Bot
  • func New(cfg Config, stateDir string, manager ServiceManager) *Bot
  • func (b *Bot) CommandPrefix() string
  • func (b *Bot) PostMessage(ctx context.Context, message string)
  • func (b *Bot) Ready() <-chan struct{}
  • func (b *Bot) Run(ctx context.Context) error
  • func (b *Bot) SetConfirmHandler(ch ConfirmHandler)
• type Command
  • func ParseCommand(message, prefix string) *Command
• type Config
• type ConfirmHandler
• type Notifier
  • func NewNotifier(sender messageSender) *Notifier
  • func (n *Notifier) DeployFailed(name, step, output string)
  • func (n *Notifier) DeployStarted(name string)
  • func (n *Notifier) DeploySucceeded(name, _ string)
  • func (n *Notifier) ServiceEvent(name, ev string)
  • func (n *Notifier) WebhookReceived(name string, info service.WebhookInfo)
• type ServiceManager

Types

type Bot

type Bot struct {
	// contains filtered or unexported fields
}

Bot is the Matrix frontend.

func New

func New(cfg Config, stateDir string, manager ServiceManager) *Bot

New constructs a Bot. The real connection, alias resolution, and crypto bootstrap happen in Run; the only I/O performed here is the optional /.well-known/matrix/client lookup when cfg.Homeserver is a bare server name. stateDir is used to derive the default crypto database path when cfg.CryptoDB is empty.

A malformed homeserver URL or a failed discovery is recorded and surfaces from Run; matching the Mattermost frontend, construction itself does not return an error.

func (*Bot) CommandPrefix

func (b *Bot) CommandPrefix() string

CommandPrefix returns the normalised prefix the bot listens for, so callers (e.g. the app's webhook confirmation prompt) can advertise the same string the bot will actually match.

func (*Bot) PostMessage

func (b *Bot) PostMessage(ctx context.Context, message string)

PostMessage renders the markdown to HTML and sends it to the configured room. mautrix transparently encrypts when client.Crypto is set and the room is encrypted. Errors are logged, not returned, since notifier callers don't have a place to surface them.

Drops the message if called before Run has completed setup: client is nil when mautrix.NewClient failed in New, and roomID is unset until resolveRoom runs. The bot is appended to the manager's notifier list during app.New, so either condition is reachable before Run finishes (or at all, if it errored).

func (*Bot) Ready

func (b *Bot) Ready() <-chan struct{}

Ready closes once Run has resolved the room and finished the crypto bootstrap, so callers know it is safe to call PostMessage.

func (*Bot) Run

func (b *Bot) Run(ctx context.Context) error

Run resolves the configured room, initialises crypto, registers sync handlers, and blocks on SyncWithContext until ctx is cancelled. mautrix reconnects internally; an error here means the loop exited for good.

func (*Bot) SetConfirmHandler

func (b *Bot) SetConfirmHandler(ch ConfirmHandler)

SetConfirmHandler installs the deploy-confirmation handler.

type Command

type Command struct {
	Action  string
	Service string
}

Command is a parsed bot command.

func ParseCommand

func ParseCommand(message, prefix string) *Command

ParseCommand returns a Command when the first whitespace-separated token of message exactly equals prefix. Otherwise it returns nil. The remaining tokens after the prefix become Action and (optionally) Service. The prefix match is case-sensitive; the action's case is preserved for the caller to fold as it sees fit.

type Config

type Config struct {
	Homeserver    string
	Room          string
	CommandPrefix string
	CryptoDB      string

	UserID      string
	DeviceID    string
	AccessToken string
	PickleKey   string
}

Config holds everything matrix.New needs to construct a Bot. The four secrets (UserID, DeviceID, AccessToken, PickleKey) are loaded from env, the rest from config.yaml.

type ConfirmHandler

type ConfirmHandler interface {
	Confirm(service string) bool
}

ConfirmHandler completes a deploy confirmation initiated by a webhook for a service with require_confirmation: true.

type Notifier

type Notifier struct {
	// contains filtered or unexported fields
}

Notifier implements service.Notifier by posting markdown messages to a configured Matrix room via Bot.PostMessage.

func NewNotifier

func NewNotifier(sender messageSender) *Notifier

NewNotifier creates a Notifier that posts events through sender.

func (*Notifier) DeployFailed

func (n *Notifier) DeployFailed(name, step, output string)

DeployFailed posts a deploy-failed notification with the failed step and output. The output is truncated from the head (keeping the tail, where the real error usually is) so the whole message stays under matrixMaxRunes.

func (*Notifier) DeployStarted

func (n *Notifier) DeployStarted(name string)

DeployStarted posts a deploy-started notification.

func (*Notifier) DeploySucceeded

func (n *Notifier) DeploySucceeded(name, _ string)

DeploySucceeded posts a deploy-succeeded notification.

func (*Notifier) ServiceEvent

func (n *Notifier) ServiceEvent(name, ev string)

ServiceEvent posts a service lifecycle event.

func (*Notifier) WebhookReceived

func (n *Notifier) WebhookReceived(name string, info service.WebhookInfo)

WebhookReceived posts a notification describing an incoming webhook that matched the named service.

type ServiceManager

type ServiceManager interface {
	Do(name, op string) string
	RequestDeploy(name string) error
	StartAll()
	StopAll()
	Reload() error
	ServiceNames() []string
	CountRunning() (int, int)
	GetAllStates() map[string]service.ServiceState
}

ServiceManager is the slice of the manager API the Matrix frontend uses. Duplicated from internal/mattermost so the two packages stay independent; extract to internal/service if a third frontend wants the same shape.