matrix

Documentation

Overview

Package matrix is the gateway's Matrix channel adapter. It talks to the Matrix client-server API directly over net/http (long-poll /sync + room send) — no SDK, matching the repo's thin-dependency ethos. The user points it at their homeserver with MATRIX_HOMESERVER + MATRIX_ACCESS_TOKEN in the global .env (a dedicated bot account's access token; this package never reads the environment itself — the gateway wires the values in).

NO END-TO-END ENCRYPTION in v1. This adapter speaks PLAIN rooms only: events in encrypted rooms arrive as m.room.encrypted and are silently ignored, because E2EE requires Olm/Megolm session state that a raw HTTP client does not carry. Invite the bot to unencrypted rooms.

Index

• type Channel
  • func New(homeserver, accessToken string, store CursorStore, mediaDir string) *Channel
  • func (c *Channel) Name() string
  • func (c *Channel) Send(ctx context.Context, conversation string, msg channels.Outbound) error
  • func (c *Channel) Start(ctx context.Context, sink channels.Sink) error
• type CursorStore

Types

type Channel

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

Channel is a Matrix client connection.

func New

func New(homeserver, accessToken string, store CursorStore, mediaDir string) *Channel

New builds a Matrix channel for the given homeserver and access token. store may be nil, in which case the since-token lives only in memory (and a restart re-reads recent history, which the router's dedup then discards). mediaDir is the gateway media spool images/audio/files are downloaded into; "" disables attachment handling (messages still flow as text).

func (*Channel) Name

func (c *Channel) Name() string

Name returns the adapter identifier.

func (*Channel) Send

func (c *Channel) Send(ctx context.Context, conversation string, msg channels.Outbound) error

Send posts a reply to a room, split with the shared chunker. Replies go out as m.notice — the Matrix bot convention — so other bots (including a second gateway) skip them and no reply loop can form. A voice rendition, when present, is uploaded and sent as m.audio first, best-effort: any failure falls back silently to the text.

func (*Channel) Start

func (c *Channel) Start(ctx context.Context, sink channels.Sink) error

Start long-polls /sync and forwards each message event as an Inbound until ctx is cancelled. The since-token is loaded from (and saved to) the cursor store so a restart resumes where it left off. Transient errors back off with jitter rather than returning, so a flaky homeserver never takes the gateway down.

type CursorStore

type CursorStore interface {
	Cursor(ctx context.Context, channel string) (string, error)
	SetCursor(ctx context.Context, channel, cursor string) error
}

CursorStore persists the /sync since-token so a restart resumes where it left off instead of replaying (and re-running) the backlog. Satisfied by the gateway's state store; nil in tests / when no persistence is wired.