Package matrix

import "github.com/matrix-org/go-neb/matrix"

Overview ▾

Package matrix provides an HTTP client that can interact with a Homeserver via r0 APIs (/sync).

It is NOT safe to access the field (or any sub-fields of) 'Rooms' concurrently. In essence, this structure MUST be treated as read-only. The matrix client will update this structure as new events arrive from the homeserver.

Internally, the client has 1 goroutine for polling the server, and 1 goroutine for processing data returned. The polling goroutine communicates to the processing goroutine by a buffered channel which feedback loops if processing takes a while as it will delay more data from being pulled down if the buffer gets full. Modification of the 'Rooms' field of the client is done EXCLUSIVELY on the processing goroutine.

Index ▾

Package files

matrix.go responses.go types.go worker.go

type Client

type Client struct {
    HomeserverURL *url.URL
    Prefix        string
    UserID        string
    AccessToken   string
    Rooms         map[string]*Room
    Worker        *Worker

    NextBatchStorer NextBatchStorer
    ClientConfig    api.ClientConfig
    // contains filtered or unexported fields

Client represents a Matrix client.

func NewClient

func NewClient(httpClient *http.Client, homeserverURL *url.URL, accessToken, userID string) *Client

NewClient creates a new Matrix Client ready for syncing

func (*Client) JoinRoom

func (cli *Client) JoinRoom(roomIDorAlias, serverName, invitingUserID string) (string, error)

JoinRoom joins the client to a room ID or alias. If serverName is specified, this will be added as a query param to instruct the homeserver to join via that server. If invitingUserID is specified, the inviting user ID will be inserted into the content of the join request. Returns a room ID.

func (*Client) SendMessageEvent

func (cli *Client) SendMessageEvent(roomID string, eventType string, contentJSON interface{}) (string, error)

SendMessageEvent sends a message event into a room, returning the event_id on success. contentJSON should be a pointer to something that can be encoded as JSON using json.Marshal.

func (*Client) SendText

func (cli *Client) SendText(roomID, text string) (string, error)

SendText sends an m.room.message event into the given room with a msgtype of m.text

func (*Client) SetDisplayName

func (cli *Client) SetDisplayName(displayName string) error

SetDisplayName sets the user's profile display name

func (*Client) StopSync

func (cli *Client) StopSync()

StopSync stops the ongoing sync started by Sync.

func (*Client) Sync

func (cli *Client) Sync()

Sync starts syncing with the provided Homeserver. This function will be invoked continually. If Sync is called twice then the first sync will be stopped.

func (cli *Client) UploadLink(link string) (string, error)

UploadLink uploads an HTTP URL and then returns an MXC URI.

func (*Client) UploadToContentRepo

func (cli *Client) UploadToContentRepo(content io.Reader, contentType string, contentLength int64) (string, error)

UploadToContentRepo uploads the given bytes to the content repository and returns an MXC URI.

type Event

type Event struct {
    StateKey  string                 `json:"state_key"`        // The state key for the event. Only present on State Events.
    Sender    string                 `json:"sender"`           // The user ID of the sender of the event
    Type      string                 `json:"type"`             // The event type
    Timestamp int                    `json:"origin_server_ts"` // The unix timestamp when this message was sent by the origin server
    ID        string                 `json:"event_id"`         // The unique ID of this event
    RoomID    string                 `json:"room_id"`          // The room the event was sent to. May be nil (e.g. for presence)
    Content   map[string]interface{} `json:"content"`          // The JSON content of the event.

Event represents a single Matrix event.

func (*Event) Body

func (event *Event) Body() (body string, ok bool)

Body returns the value of the "body" key in the event content if it is present and is a string.

func (*Event) MessageType

func (event *Event) MessageType() (msgtype string, ok bool)

MessageType returns the value of the "msgtype" key in the event content if it is present and is a string.

type HTMLMessage

type HTMLMessage struct {
    Body          string `json:"body"`
    MsgType       string `json:"msgtype"`
    Format        string `json:"format"`
    FormattedBody string `json:"formatted_body"`

An HTMLMessage is the contents of a Matrix HTML formated message event.

func GetHTMLMessage

func GetHTMLMessage(msgtype, htmlText string) HTMLMessage

GetHTMLMessage returns an HTMLMessage with the body set to a stripped version of the provided HTML, in addition to the provided HTML.

type ImageInfo

type ImageInfo struct {
    Height   uint   `json:"h"`
    Width    uint   `json:"w"`
    Mimetype string `json:"mimetype"`
    Size     uint   `json:"size"`

ImageInfo contains info about an image

type ImageMessage

type ImageMessage struct {
    MsgType string    `json:"msgtype"`
    Body    string    `json:"body"`
    URL     string    `json:"url"`
    Info    ImageInfo `json:"info"`

ImageMessage is an m.image event

type NextBatchStorer

type NextBatchStorer interface {
    // Save a next_batch token for a given user. Best effort.
    Save(userID, nextBatch string)
    // Load a next_batch token for a given user. Return an empty string if no token exists.
    Load(userID string) string

NextBatchStorer controls loading/saving of next_batch tokens for users

type OnEventListener

type OnEventListener func(*Event)

OnEventListener can be used with Worker.OnEventType to be informed of incoming events.

type Room

type Room struct {
    ID       string
    State    map[string]map[string]*Event
    Timeline []Event

Room represents a single Matrix room.

func NewRoom

func NewRoom(roomID string) *Room

NewRoom creates a new Room with the given ID

func (Room) GetMembershipState

func (room Room) GetMembershipState(userID string) string

GetMembershipState returns the membership state of the given user ID in this room. If there is no entry for this member, 'leave' is returned for consistency with left users.

func (Room) GetStateEvent

func (room Room) GetStateEvent(eventType string, stateKey string) *Event

GetStateEvent returns the state event for the given type/state_key combo, or nil.

func (Room) UpdateState

func (room Room) UpdateState(event *Event)

UpdateState updates the room's current state with the given Event. This will clobber events based on the type/state_key combination.

type StarterLinkMessage

type StarterLinkMessage struct {
    Body string
    Link string

StarterLinkMessage represents a message with a starter_link custom data.

func (StarterLinkMessage) MarshalJSON

func (m StarterLinkMessage) MarshalJSON() ([]byte, error)

MarshalJSON converts this message into actual event content JSON.

type TextMessage

type TextMessage struct {
    MsgType string `json:"msgtype"`
    Body    string `json:"body"`

TextMessage is the contents of a Matrix formated message event.

type Worker

type Worker struct {
    // contains filtered or unexported fields

Worker processes incoming events and updates the Matrix client's data structures. It also informs any attached listeners of the new events.

func (*Worker) OnEventType

func (worker *Worker) OnEventType(eventType string, callback OnEventListener)

OnEventType allows callers to be notified when there are new events for the given event type. There are no duplicate checks.