gotrix

README

gotrix

Gotrix is a work-in-progress implementation of the client portion of Matrix's client-server API. It is still actively being developed and the API may change especially when they are recently introduced.

It currently implements all of the parts mandated by specification but does not implement all modules available. A list of available modules that are done can be found at TODO.md.

If you require the use of features that have not been implemented yet, gomatrix and mautrix-go are alternative clients of Matrix in Go.

Documentation

Index

• Variables
• type Client
  • func Discover(serverName string) (*Client, error)
  • func DiscoverWithClient(httpClient httputil.Client, serverName string) (*Client, error)
  • func New(homeServerHost string) (*Client, error)
  • func NewWithClient(httpClient httputil.Client, serverName string) (*Client, error)
  • func (c *Client) AddHandler(function interface{}) error
  • func (c *Client) Close() error
  • func (c *Client) EachRoomState(roomID matrix.RoomID, typ event.Type, f func(string, event.StateEvent) error) error
  • func (c *Client) FormatSpoiler(reason string, spoilerText string) (body string, formatted string, _ error)
  • func (c *Client) LoginPassword(username, password string) error
  • func (c *Client) LoginSSO() (string, func() error, error)
  • func (c *Client) LoginToken(token string) error
  • func (c *Client) MarkRoomAsDM(remoteID matrix.UserID, roomID matrix.RoomID) error
  • func (c *Client) MemberAvatar(roomID matrix.RoomID, userID matrix.UserID) (*matrix.URL, error)
  • func (c *Client) MemberName(roomID matrix.RoomID, userID matrix.UserID) (string, error)
  • func (c *Client) MemberNames(roomID matrix.RoomID, userIDs []matrix.UserID) ([]string, error)
  • func (c *Client) MentionRoom(roomID matrix.RoomID) (body string, formatted string)
  • func (c *Client) MentionUser(userID matrix.UserID, roomID matrix.RoomID) (body string, formatted string)
  • func (c *Client) Next() string
  • func (c *Client) Open() error
  • func (c *Client) OpenWithNext(next string) error
  • func (c *Client) RoomAvatar(roomID matrix.RoomID) (*matrix.URL, error)
  • func (c *Client) RoomName(roomID matrix.RoomID) (string, error)
  • func (c *Client) RoomState(roomID matrix.RoomID, eventType event.Type, key string) (event.StateEvent, error)
  • func (c *Client) RoomSummary(roomID matrix.RoomID) (api.SyncRoomSummary, error)
  • func (c *Client) SendAudio(roomID matrix.RoomID, file File) (matrix.EventID, error)
  • func (c *Client) SendEmote(roomID matrix.RoomID, content string) (matrix.EventID, error)
  • func (c *Client) SendFile(roomID matrix.RoomID, file File) (matrix.EventID, error)
  • func (c *Client) SendImage(roomID matrix.RoomID, file File) (matrix.EventID, error)
  • func (c *Client) SendLocation(roomID matrix.RoomID, geoURI matrix.GeoURI, caption string) (matrix.EventID, error)
  • func (c *Client) SendMessage(roomID matrix.RoomID, content string) (matrix.EventID, error)
  • func (c *Client) SendNotice(roomID matrix.RoomID, content string) (matrix.EventID, error)
  • func (c *Client) SendVideo(roomID matrix.RoomID, file File) (matrix.EventID, error)
  • func (c Client) WithContext(ctx context.Context) *Client
• type File
• type Handler
• type State
• type SyncOptions

Variables

var DefaultSyncOptions = SyncOptions{
	Filter: event.GlobalFilter{
		Room: event.RoomFilter{
			IncludeLeave: false,
			State: event.StateFilter{
				LazyLoadMembers: true,
			},
			Timeline: event.RoomEventFilter{
				Limit:           50,
				LazyLoadMembers: true,
			},
		},
	},
	Timeout:        5 * time.Second,
	MinBackoffTime: 1 * time.Second,
	MaxBackoffTime: 300 * time.Second,
}

DefaultSyncOptions is the default sync options instance used on every Client creation.

var ErrInvalidStateEvent = errors.New("invalid state event has been returned by homeserver")

ErrInvalidStateEvent is returned by (*Client).RoomState and (*Client).RoomStates when homeserver returns an event that is not a known state event when a state event is expected.

var ErrRoomAvatarNotFound = errors.New("user is alone in the room and a room avatar has not been set")

ErrRoomAvatarNotFound is returned by RoomAvatar when the room avatar cannot be discovered.

var ErrStopIter = errors.New("stop iterating on EachRoomState")

ErrStopIter is an error used to denote that the iteration on EachRoomState should be stopped.

var MemberAvatarNotFound = errors.New("member avatar cannot be found")

MemberAvatarNotFound is returned by MemberAvatar when a member's avatar cannot be determined.

var SuccessHTML = defaultSuccessHTML

SuccessHTML is the HTML displayed when the user successfully logs in through SSO.

Types

type Client

type Client struct {
	*api.Client

	SyncOpts SyncOptions
	Handler  Handler
	State    State
	// contains filtered or unexported fields
}

Client is an instance of a higher level client.

func Discover

func Discover(serverName string) (*Client, error)

Discover is a helper function that calls DiscoverWithClient with the default HTTP client.

func DiscoverWithClient

func DiscoverWithClient(httpClient httputil.Client, serverName string) (*Client, error)

DiscoverWithClient attempts to discover the homeserver using the provided server name.

This allows the host address to be extracted from the user ID and used to discover the homeserver host in a way that is spec-compliant.

func New

func New(homeServerHost string) (*Client, error)

New creates a client with the provided host URL and the default HTTP client. It assumes https if the scheme is not provided.

func NewWithClient

func NewWithClient(httpClient httputil.Client, serverName string) (*Client, error)

NewWithClient creates a client with the provided host URL and the provided client. It assumes https if the scheme is not provided.

func (*Client) AddHandler

func (c *Client) AddHandler(function interface{}) error

AddHandler adds the handler to the list of handlers.

func (*Client) Close

func (c *Client) Close() error

Close signals to the event loop to stop and wait for it to finish.

func (*Client) EachRoomState

func (c *Client) EachRoomState(roomID matrix.RoomID, typ event.Type, f func(string, event.StateEvent) error) error

EachRoomState iterates through all events with the specified type, stopping if f returns ErrIterStop.

func (*Client) FormatSpoiler

func (c *Client) FormatSpoiler(reason string, spoilerText string) (body string, formatted string, _ error)

FormatSpoiler creates the intended spoiler format for a spoiler message. Adhering to the spec, the spoiler text is uploaded to MXC as a plaintext to be included in the body. This function should therefore not be used in encrypted rooms to prevent leaks.

func (*Client) LoginPassword

func (c *Client) LoginPassword(username, password string) error

LoginPassword authenticates the client using the provided username and password.

func (*Client) LoginSSO

func (c *Client) LoginSSO() (string, func() error, error)

LoginSSO returns a URL that can be used to log the user in through SSO and starts a HTTP server to listen to the response from the homeserver. It automatically cleans up the HTTP server when the context the client has expires or when the user logs in successfully.

The returned function blocks until the login finishes or is canceled and returns an error if the login was unsuccessful.

func (*Client) LoginToken

func (c *Client) LoginToken(token string) error

LoginToken authenticates the client using the provided token.

func (*Client) MarkRoomAsDM

func (c *Client) MarkRoomAsDM(remoteID matrix.UserID, roomID matrix.RoomID) error

MarkRoomAsDM fetches the DM room list, appends the provided room and reuploads the list. It is the caller's duty to make sure only one instance is called at once.

func (*Client) MemberAvatar

func (c *Client) MemberAvatar(roomID matrix.RoomID, userID matrix.UserID) (*matrix.URL, error)

MemberAvatar determines the member's avatar by checking for a room member event with avatar and falling back to their global avatar. An error is returned if the avatar cannot be determined.

func (*Client) MemberName

func (c *Client) MemberName(roomID matrix.RoomID, userID matrix.UserID) (string, error)

MemberName calculates the display name of a member. Note that a user joining might invalidate some names if they share the same display name as disambiguation will become necessary.

Use the Client.MemberNames variant when generating member name for multiple users to reduce duplicate work.

func (*Client) MemberNames

func (c *Client) MemberNames(roomID matrix.RoomID, userIDs []matrix.UserID) ([]string, error)

MemberNames calculates the display name of all the users provided.

func (*Client) MentionRoom

func (c *Client) MentionRoom(roomID matrix.RoomID) (body string, formatted string)

MentionRoom creates the intended mention format for a room in normal body and formatted body.

func (*Client) MentionUser

func (c *Client) MentionUser(userID matrix.UserID, roomID matrix.RoomID) (body string, formatted string)

MentionUser creates the intended mention format for a user in normal body and formatted body.

func (*Client) Next

func (c *Client) Next() string

Next returns the current Next synchronization argument. Next can ONLY be called once the Client is closed, otherwise a panic will occur.

func (*Client) Open

func (c *Client) Open() error

Open starts the event loop of the client with a background context.

func (*Client) OpenWithNext

func (c *Client) OpenWithNext(next string) error

OpenWithNext starts the event loop with the given next string that resumes the sync loop. If next is empty, then an initial sync will be done.

func (*Client) RoomAvatar

func (c *Client) RoomAvatar(roomID matrix.RoomID) (*matrix.URL, error)

RoomAvatar retrieves the avatar of a room. It falls back to the profile picture of the first user to join the room that is not the current user otherwise. If the current user is alone, it returns nil and an error.

func (*Client) RoomName

func (c *Client) RoomName(roomID matrix.RoomID) (string, error)

RoomName calculates the display name of a room.

func (*Client) RoomState

func (c *Client) RoomState(roomID matrix.RoomID, eventType event.Type, key string) (event.StateEvent, error)

RoomState queries the internal State for the given RoomEvent. If the State does not have that event, it queries the homeserver directly.

func (*Client) RoomSummary

func (c *Client) RoomSummary(roomID matrix.RoomID) (api.SyncRoomSummary, error)

RoomSummary queries the State for the summary of a room, commonly used for generating room name. To follow the room name generation strategy of the specification, use Client.RoomName instead.

func (*Client) SendAudio

func (c *Client) SendAudio(roomID matrix.RoomID, file File) (matrix.EventID, error)

SendAudio uploads the provided audio file to the server and sends a message containing it to the designated room.

func (*Client) SendEmote

func (c *Client) SendEmote(roomID matrix.RoomID, content string) (matrix.EventID, error)

SendEmote sends a emote to the provided room ID with the provided content.

Emote is a regular message but is sent as someone performing it (/me in IRC).

func (*Client) SendFile

func (c *Client) SendFile(roomID matrix.RoomID, file File) (matrix.EventID, error)

SendFile uploads the provided file to the server and sends a message containing it to the designated room.

func (*Client) SendImage

func (c *Client) SendImage(roomID matrix.RoomID, file File) (matrix.EventID, error)

SendImage uploads the provided image to the server and sends a message containing it to the designated room.

func (*Client) SendLocation

func (c *Client) SendLocation(roomID matrix.RoomID, geoURI matrix.GeoURI, caption string) (matrix.EventID, error)

SendLocation sends the provided location to the provided room ID.

func (*Client) SendMessage

func (c *Client) SendMessage(roomID matrix.RoomID, content string) (matrix.EventID, error)

SendMessage sends a message to the provided room ID with the provided content.

func (*Client) SendNotice

func (c *Client) SendNotice(roomID matrix.RoomID, content string) (matrix.EventID, error)

SendNotice sends a notice to the provided room ID with the provided content.

Notice are the same as messages except they're not intended to be parsed by bots (ie. other bots' messages).

func (*Client) SendVideo

func (c *Client) SendVideo(roomID matrix.RoomID, file File) (matrix.EventID, error)

SendVideo uploads the provided video file to the server and sends a message containing it to the designated room.

func (Client) WithContext

func (c Client) WithContext(ctx context.Context) *Client

WithContext creates a copy of the client that uses the provided context.

type File

type File struct {
	Name     string
	MIMEType string
	Content  io.ReadCloser
	Caption  string // Set to filename if empty.

	FileInfo  *event.FileInfo
	ImageInfo *event.ImageInfo
	AudioInfo *event.AudioInfo
	VideoInfo *event.VideoInfo
}

File is a file that can be uploaded to Matrix homeserver.

type Handler

type Handler interface {
	Handle(cli *Client, event event.Event)
	HandleRaw(cli *Client, event event.RawEvent)
	AddHandler(toCall interface{}) error
}

Handler is the interface that represents the methods the client needs from the handler. An event is always passed into HandleRaw and is passed into Handle when it is successfully parsed.

type State

type State interface {
	// RoomState returns the latest event in a room with the specified type.
	// If it is found in the cache, error will be nil.
	// Note that (nil, nil) should be returned if the cache can be certain the event type never occurred.
	RoomState(roomID matrix.RoomID, eventType event.Type, stateKey string) (event.StateEvent, error)
	// EachRoomState calls f for every event stored in the state.
	// To abort iteration, f should return ErrStopIter.
	// This function can return the error returned by f or errors while getting data for iteration.
	EachRoomState(roomID matrix.RoomID, eventType event.Type, f func(key string, e event.StateEvent) error) error
	// RoomSummary returns the summary of a room as received in sync response.
	RoomSummary(roomID matrix.RoomID) (api.SyncRoomSummary, error)
	// AddEvent adds the needed events from the given sync response.
	// It is up to the implementation to pick and add the needed events inside the response.
	AddEvents(*api.SyncResponse) error
}

State represents the required functions for a state.

type SyncOptions

type SyncOptions struct {
	Filter         event.GlobalFilter
	Timeout        time.Duration
	MinBackoffTime time.Duration
	MaxBackoffTime time.Duration
}

SyncOptions contains options for the /sync endpoint that is used once the Client is opened.