matrix

Documentation

Index

• Variables
• func MapAPIError(e error, m ErrorMap) error
• func StatusCode(e error) int
• type APIError
  • func (e APIError) Error() string
• type Capabilities
  • func (c Capabilities) ChangePassword() (CapabilityChangePassword, error)
  • func (c Capabilities) RoomVersion() (CapabilityRoomVersion, error)
• type CapabilityChangePassword
• type CapabilityRoomVersion
• type DeviceID
• type Duration
  • func (d Duration) Duration() time.Duration
• type ErrorCode
  • func ErrCode(e error) ErrorCode
• type ErrorMap
• type EventID
• type GeoURI
  • func (g GeoURI) Altitude() (float64, error)
  • func (g GeoURI) Lat() (float64, error)
  • func (g GeoURI) Long() (float64, error)
  • func (g GeoURI) Parse() (float64, float64, *float64, error)
• type HTTPError
  • func NewHTTPError(code int, underlyingError error) HTTPError
  • func (h HTTPError) Error() string
  • func (h HTTPError) Unwrap() error
• type IDServerUnbindResult
• type Identifier
• type IdentifierType
• type LoginMethod
  • func (l LoginMethod) FallbackURL(authServerHost string, sessionID string) string
• type Presence
• type RoomID
• type RoomVersionStability
• type Tag
• type TagName
  • func (t TagName) Namespace(n string) bool
• type Timestamp
  • func (t Timestamp) Time() time.Time
• type URL
• type UserID
  • func (userID UserID) Parse() (localPart, serverName string, err error)

Variables

var (
	// ErrInvalidGeoURI represents an error in parsing geo URI.
	ErrInvalidGeoURI = errors.New("invalid geo URI")
	// ErrAltitudeNotPresent is returned when altitude is requested but not present.
	ErrAltitudeNotPresent = errors.New("altitude not present")
)

var ErrInvalidUserID = errors.New("invalid user ID passed")

ErrInvalidUserID is an error generated by ParseUserID when the user ID is invalid.

Functions

func MapAPIError

func MapAPIError(e error, m ErrorMap) error

MapAPIError is a helper function that maps API errors to its concrete error types as provided by the user.

Unmatched errors are returned as-is.

func StatusCode

func StatusCode(e error) int

StatusCode takes in an error and return the HTTP status code associated with it.

If it's not a HTTPError, it returns -1 instead.

Types

type APIError

type APIError struct {
	// Code and Message should be included in every API error.
	Code    ErrorCode `json:"errcode"`
	Message string    `json:"error"`

	// SoftLogout is included in invalid token errors.
	// If it's true, the client should just log back in.
	// If it's false, the client should purge all its cache before
	// logging back in.
	SoftLogout bool `json:"soft_logout"`

	// RetryAfterMillisecond is included in rate limit errors.
	RetryAfterMillisecond int `json:"retry_after_ms"`
}

APIError represents an API error as returned by the Matrix server.

It is always wrapped around by HTTPError.

func (APIError) Error

func (e APIError) Error() string

Error makes API Error implement the `error` interface.

type Capabilities

type Capabilities map[string]json.RawMessage

Capabilities represent the server's capabilities as defined in https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-capabilities.

func (Capabilities) ChangePassword

func (c Capabilities) ChangePassword() (CapabilityChangePassword, error)

ChangePassword retrieves CapabilityChangePassword from the Capabilities.

func (Capabilities) RoomVersion

func (c Capabilities) RoomVersion() (CapabilityRoomVersion, error)

RoomVersion retrieves CapabilityRoomVersion from the Capabilities.

type CapabilityChangePassword

type CapabilityChangePassword struct {
	Enabled bool `json:"enabled"`
}

CapabilityChangePassword contains whether the server has password change enabled. If it is disabled, it's probably delegated to the identity server.

type CapabilityRoomVersion

type CapabilityRoomVersion struct {
	Default   string `json:"default"`
	Available map[string]RoomVersionStability
}

CapabilityRoomVersion contains information of the version of the rooms.

type DeviceID

type DeviceID string

DeviceID is a magic string that identifies a device.

type Duration

type Duration int64

Duration is a duration of time measured in milliseconds.

func (Duration) Duration

func (d Duration) Duration() time.Duration

Duration converts a duration into valid Go duration.

type ErrorCode

type ErrorCode string

ErrorCode represents an error code that is found in REST errors.

const (
	// Common error codes
	CodeForbidden     ErrorCode = "M_FORBIDDEN"
	CodeUnknownToken  ErrorCode = "M_UNKNOWN_TOKEN"
	CodeMissingToken  ErrorCode = "M_MISSING_TOKEN"
	CodeBadJSON       ErrorCode = "M_BAD_JSON"
	CodeNotJSON       ErrorCode = "M_NOT_JSON"
	CodeNotFound      ErrorCode = "M_NOT_FOUND"
	CodeLimitExceeded ErrorCode = "M_LIMIT_EXCEEDED"
	CodeUnknown       ErrorCode = "M_UNKNOWN"

	// Other error codes the client might encounter
	CodeUnrecognized                 ErrorCode = "M_UNRECOGNIZED"
	CodeUnauthorized                 ErrorCode = "M_UNAUTHORIZED"
	CodeUserDeactivated              ErrorCode = "M_USER_DEACTIVATED"
	CodeUserInUse                    ErrorCode = "M_USER_IN_USE"
	CodeInvalidUsername              ErrorCode = "M_INVALID_USERNAME"
	CodeRoomInUse                    ErrorCode = "M_ROOM_IN_USE"
	CodeInvalidRoomState             ErrorCode = "M_INVALID_ROOM_STATE"
	CodeThreePIDInUse                ErrorCode = "M_THREEPID_IN_USE"
	CodeThreePIDNotFound             ErrorCode = "M_THREEPID_NOT_FOUND"
	CodeThreePIDAuthFailed           ErrorCode = "M_THREEPID_AUTH_FAILED"
	CodeThreePIDDenied               ErrorCode = "M_THREEPID_DENIED"
	CodeServerNotTrusted             ErrorCode = "M_SERVER_NOT_TRUSTED"
	CodeUnsupportedRoomVersion       ErrorCode = "M_UNSUPPORTED_ROOM_VERSION"
	CodeIncompatibleRoomVersion      ErrorCode = "M_INCOMPATIBLE_ROOM_VERSION"
	CodeBadState                     ErrorCode = "M_BAD_STATE"
	CodeGuestAccessForbidden         ErrorCode = "M_GUEST_ACCESS_FORBIDDEN"
	CodeCaptchaNeeded                ErrorCode = "M_CAPTCHA_NEEDED"
	CodeMissingParam                 ErrorCode = "M_MISSING_PARAM"
	CodeInvalidParam                 ErrorCode = "M_INVALID_PARAM"
	CodeTooLarge                     ErrorCode = "M_TOO_LARGE"
	CodeExclusive                    ErrorCode = "M_EXCLUSIVE"
	CodeResourceLimitExceeded        ErrorCode = "M_RESOURCE_LIMIT_EXCEEDED"
	CodeCannotLeaveServiceNoticeRoom ErrorCode = "M_CANNOT_LEAVE_SERVICE_NOTICE_ROOM"

	// Codes that are documented on other sections
	CodeWeakPassword ErrorCode = "M_WEAK_PASSWORD"
)

List of official error codes. It can be found at https://matrix.org/docs/spec/client_server/r0.6.1#api-standards.

func ErrCode

func ErrCode(e error) ErrorCode

ErrCode takes in an error and return the API error code associated with it.

If it's not an APIError, it returns an empty string instead.

type ErrorMap

type ErrorMap map[ErrorCode]error

ErrorMap is a shorthand for map[ErrorCode]error.

type EventID

type EventID string

EventID is a string that identifies an event.

type GeoURI

type GeoURI string

GeoURI is a geographic URI.

func (GeoURI) Altitude

func (g GeoURI) Altitude() (float64, error)

Altitude returns the altitude specified in the GeoURI.

func (GeoURI) Lat

func (g GeoURI) Lat() (float64, error)

Lat returns the latitude specified in the GeoURI.

func (GeoURI) Long

func (g GeoURI) Long() (float64, error)

Long returns the longitude specified in the GeoURI.

func (GeoURI) Parse

func (g GeoURI) Parse() (float64, float64, *float64, error)

Parse returns the lat, long and altitude (if present). This only implements simple parsing. For more details, use the specific functions.

type HTTPError

type HTTPError struct {
	Code            int
	UnderlyingError error
}

HTTPError represents an error while decoding response. It contains the status code and the actual error.

func NewHTTPError

func NewHTTPError(code int, underlyingError error) HTTPError

NewHTTPError constructs a new HTTP error with the provided details.

func (HTTPError) Error

func (h HTTPError) Error() string

Error makes HTTPError implement the `error` interface.

func (HTTPError) Unwrap

func (h HTTPError) Unwrap() error

Unwrap allows the underlying error to be exposed.

type IDServerUnbindResult

type IDServerUnbindResult string

IDServerUnbindResult represents whether 3PIDs has been unbound from the identity server successfully.

const (
	// UnbindSuccess represents success in unbinding.
	UnbindSuccess IDServerUnbindResult = "success"
	// UnbindNoSupport means that the homeserver is unable to determine
	// the identity server to unbind from.
	UnbindNoSupport IDServerUnbindResult = "no-support"
)

type Identifier

type Identifier struct {
	Type IdentifierType `json:"type"`

	// User is valid when the type is IdentifierUser.
	// It only contains the local part.
	User string `json:"user,omitempty"`

	// Medium and Address are valid when the type is IdentifierThirdparty.
	Medium  string `json:"medium,omitempty"`
	Address string `json:"address,omitempty"`

	// Country and Phone are valid when the type is IdentifierPhone.
	Country string `json:"country,omitempty"`
	Phone   string `json:"phone,omitempty"`
}

Identifier represents a struct with all possible fields of identifying a user.

type IdentifierType

type IdentifierType string

IdentifierType represents methods in which the user can identify themselves.

const (
	IdentifierUser       IdentifierType = "m.id.user"
	IdentifierThirdparty IdentifierType = "m.id.thirdparty"
	IdentifierPhone      IdentifierType = "m.id.phone"
)

Official list of Identifier types. It can be found at https://matrix.org/docs/spec/client_server/r0.6.1#identifier-types.

type LoginMethod

type LoginMethod string

LoginMethod represents a possible login method that can be used to authenticate.

const (
	LoginPassword  LoginMethod = "m.login.password"
	LoginRecaptcha LoginMethod = "m.login.recaptcha"
	LoginToken     LoginMethod = "m.login.token"
	LoginOAuth2    LoginMethod = "m.login.oauth2"
	LoginSSO       LoginMethod = "m.login.sso"
	LoginEmail     LoginMethod = "m.login.email.identity"
	LoginPhone     LoginMethod = "m.login.msisdn"
	LoginDummy     LoginMethod = "m.login.dummy"
)

List of official authentications. It can be found here: https://matrix.org/docs/spec/client_server/r0.6.1#authentication-types.

const (
	LoginAppservice LoginMethod = "uk.half-shot.msc2778.login.application_service"
)

List of famous custom authentications.

func (LoginMethod) FallbackURL

func (l LoginMethod) FallbackURL(authServerHost string, sessionID string) string

FallbackURL generates the URL that the application can open in order to finish the auth process. This can be used when the auth method is not natively supported by the client.

type Presence

type Presence string

Presence represents the status of the client to set while the client is polling.

const (
	PresenceOnline  Presence = "online"
	PresenceOffline Presence = "offline"
	PresenceIdle    Presence = "unavailable"
)

The three possible status to be in are online, offline (invisible) and idle (unavailable).

type RoomID

type RoomID string

RoomID is a magic string that identifies a room.

type RoomVersionStability

type RoomVersionStability string

RoomVersionStability expresses the stability status of a room version.

const (
	RoomVersionStable   RoomVersionStability = "stable"
	RoomVersionUnstable RoomVersionStability = "unstable"
)

RoomVersionStability can either be "stable" or "unstable".

type Tag

type Tag struct {
	// Ordering information as a number between 0 and 1.
	// Compared such that 0 is displayed first, and an order of `0.2` would
	// come before a room with order `0.7`.
	//
	// If Order is nil, it should appear last.
	Order *float64 `json:"order"`
}

type TagName

type TagName string

var (
	TagFavourites   TagName = "m.favourites"
	TagLowPriority  TagName = "m.lowpriority"
	TagServerNotice TagName = "m.server_notice"
)

func (TagName) Namespace

func (t TagName) Namespace(n string) bool

Namespace returns whether the specified tagname has the namespace.

type Timestamp

type Timestamp int64

Timestamp is a timestamp in milliseconds since Unix time.

func (Timestamp) Time

func (t Timestamp) Time() time.Time

Time converts a timestamp into valid Go time.

type URL

type URL string

URL is a URI which is likely to be MXC URI.

type UserID

type UserID string

UserID is a user's full qualified identifier. It includes the preceding @.

func (UserID) Parse

func (userID UserID) Parse() (localPart, serverName string, err error)

Parse attempts to split the provided user ID into the local part and the host name. It does not make any attempt at validating if the local part and the host name is valid.

It returns ErrInvalidUserID when the ID cannot be made sense of.