api

Documentation

Index

• Constants
• func CheckEventHasBody(body string) func(e Event) bool
• func CheckEventHasEventID(eventID string) func(e Event) bool
• func CheckEventHasMembership(target, membership string) func(e Event) bool
• type Client
• type ClientCreationOpts
  • func NewClientCreationOpts(c *client.CSAPI) ClientCreationOpts
• type ClientType
• type ClientTypeLang
• type Event
• type LanguageBindings
• type LoggedClient
  • func (c *LoggedClient) Close(t ct.TestLike)
  • func (c *LoggedClient) CurrentAccessToken(t ct.TestLike) string
  • func (c *LoggedClient) DeletePersistentStorage(t ct.TestLike)
  • func (c *LoggedClient) ForceClose(t ct.TestLike)
  • func (c *LoggedClient) IsRoomEncrypted(t ct.TestLike, roomID string) (bool, error)
  • func (c *LoggedClient) LoadBackup(t ct.TestLike, recoveryKey string) error
  • func (c *LoggedClient) Login(t ct.TestLike, opts ClientCreationOpts) error
  • func (c *LoggedClient) MustBackpaginate(t ct.TestLike, roomID string, count int)
  • func (c *LoggedClient) MustBackupKeys(t ct.TestLike) (recoveryKey string)
  • func (c *LoggedClient) MustGetEvent(t ct.TestLike, roomID, eventID string) Event
  • func (c *LoggedClient) MustLoadBackup(t ct.TestLike, recoveryKey string)
  • func (c *LoggedClient) MustStartSyncing(t ct.TestLike) (stopSyncing func())
  • func (c *LoggedClient) SendMessage(t ct.TestLike, roomID, text string) (eventID string)
  • func (c *LoggedClient) StartSyncing(t ct.TestLike) (stopSyncing func(), err error)
  • func (c *LoggedClient) TrySendMessage(t ct.TestLike, roomID, text string) (eventID string, err error)
  • func (c *LoggedClient) WaitUntilEventInRoom(t ct.TestLike, roomID string, checker func(e Event) bool) Waiter
• type MockT
  • func (t *MockT) Error(args ...any)
  • func (t *MockT) Errorf(f string, args ...any)
  • func (t *MockT) Failed() bool
  • func (t *MockT) Fatalf(f string, args ...any)
  • func (t *MockT) Helper()
  • func (t *MockT) Logf(f string, args ...any)
  • func (t *MockT) Name() string
  • func (t *MockT) Skipf(f string, args ...any)
• type Notification
• type Waiter

Constants

const ProcessNameNSE string = "NSE"

magic value for EnableCrossProcessRefreshLockProcessName which configures the FFI client according to iOS NSE.

Functions

func CheckEventHasBody

func CheckEventHasBody(body string) func(e Event) bool

func CheckEventHasEventID

func CheckEventHasEventID(eventID string) func(e Event) bool

func CheckEventHasMembership

func CheckEventHasMembership(target, membership string) func(e Event) bool

Types

type Client

type Client interface {
	// Close is called to clean up resources.
	// Specifically, we need to shut off existing browsers and any FFI bindings.
	// If we get callbacks/events after this point, tests may panic if the callbacks
	// log messages.
	Close(t ct.TestLike)
	// ForceClose should uncleanly shut down the client e.g
	// sending SIGKILL. This is typically useful for tests which want to explicitly test
	// unclean shutdowns.
	ForceClose(t ct.TestLike)
	// Remove any persistent storage, if it was enabled.
	DeletePersistentStorage(t ct.TestLike)
	Login(t ct.TestLike, opts ClientCreationOpts) error
	// MustStartSyncing to begin syncing from sync v2 / sliding sync.
	// Tests should call stopSyncing() at the end of the test.
	// MUST BLOCK until the initial sync is complete.
	// Fails the test if there was a problem syncing.
	MustStartSyncing(t ct.TestLike) (stopSyncing func())
	// StartSyncing to begin syncing from sync v2 / sliding sync.
	// Tests should call stopSyncing() at the end of the test.
	// MUST BLOCK until the initial sync is complete.
	// Returns an error if there was a problem syncing.
	StartSyncing(t ct.TestLike) (stopSyncing func(), err error)
	// IsRoomEncrypted returns true if the room is encrypted. May return an error e.g if you
	// provide a bogus room ID.
	IsRoomEncrypted(t ct.TestLike, roomID string) (bool, error)
	// SendMessage sends the given text as an m.room.message with msgtype:m.text into the given
	// room. Returns the event ID of the sent event, so MUST BLOCK until the event has been sent.
	SendMessage(t ct.TestLike, roomID, text string) (eventID string)
	// TrySendMessage tries to send the message, but can fail.
	TrySendMessage(t ct.TestLike, roomID, text string) (eventID string, err error)
	// Wait until an event is seen in the given room. The checker functions can be custom or you can use
	// a pre-defined one like api.CheckEventHasMembership, api.CheckEventHasBody, or api.CheckEventHasEventID.
	WaitUntilEventInRoom(t ct.TestLike, roomID string, checker func(e Event) bool) Waiter
	// Backpaginate in this room by `count` events.
	MustBackpaginate(t ct.TestLike, roomID string, count int)
	// MustGetEvent will return the client's view of this event, or fail the test if the event cannot be found.
	MustGetEvent(t ct.TestLike, roomID, eventID string) Event
	// MustBackupKeys will backup E2EE keys, else fail the test.
	MustBackupKeys(t ct.TestLike) (recoveryKey string)
	// MustLoadBackup will recover E2EE keys from the latest backup, else fail the test.
	MustLoadBackup(t ct.TestLike, recoveryKey string)
	// LoadBackup will recover E2EE keys from the latest backup, else return an error.
	LoadBackup(t ct.TestLike, recoveryKey string) error
	// GetNotification gets push notification-like information for the given event. If there is a problem, an error is returned.
	GetNotification(t ct.TestLike, roomID, eventID string) (*Notification, error)
	// Log something to stdout and the underlying client log file
	Logf(t ct.TestLike, format string, args ...interface{})
	// The user for this client
	UserID() string
	// The current access token for this client
	CurrentAccessToken(t ct.TestLike) string
	Type() ClientTypeLang
	Opts() ClientCreationOpts
}

Client represents a generic crypto client. It is an abstraction to allow tests to interact with JS and FFI bindings in an agnostic way.

type ClientCreationOpts

type ClientCreationOpts struct {
	// Required. The base URL of the homeserver.
	BaseURL string
	// Required. The user to login as.
	UserID string
	// Required. The password for this account.
	Password string

	// Optional. If true, persistent storage will be used for the same user|device ID.
	PersistentStorage bool
	// Required for rust clients. The URL of the sliding sync proxy.
	SlidingSyncURL string
	// Optional. Set this to login with this device ID.
	DeviceID string

	// Rust only. If set, enables the cross process refresh lock on the FFI client with the process name provided.
	EnableCrossProcessRefreshLockProcessName string
	// Rust only. If set with EnableCrossProcessRefreshLockProcessName=ProcessNameNSE, the client will be seeded
	// with a logged in session.
	AccessToken string
}

ClientCreationOpts are options to use when creating crypto clients.

This contains a mixture of generic options which can be used across any client, and specific options which are only supported in some clients. These are clearly documented.

func NewClientCreationOpts

func NewClientCreationOpts(c *client.CSAPI) ClientCreationOpts

type ClientType

type ClientType struct {
	Lang ClientTypeLang // rust or js
	HS   string         // hs1 or hs2
}

type ClientTypeLang

type ClientTypeLang string

var (
	ClientTypeRust ClientTypeLang = "rust"
	ClientTypeJS   ClientTypeLang = "js"
)

type Event

type Event struct {
	ID     string
	Text   string // FFI bindings don't expose the content object
	Sender string
	// FFI bindings don't expose state key
	Target string
	// FFI bindings don't expose type
	Membership      string
	FailedToDecrypt bool
}

type LanguageBindings

type LanguageBindings interface {
	// PreTestRun is a hook which is executed before any tests run. This can be used to
	// clean up old log files from previous runs. 'contextID' is any specific scoping information
	// to consider.
	PreTestRun(contextID string)
	// PostTestRun is a hook which is executed after all tests have run. This can be used
	// to flush test logs. 'contextID' is any specific scoping information
	// to consider.
	PostTestRun(contextID string)
	// MustCreateClient is called to create a new client in this language. If the client cannot
	// be created, the test should be failed by calling ct.Fatalf(t, ...).
	MustCreateClient(t ct.TestLike, cfg ClientCreationOpts) Client
}

LanguageBindings is the interface any new language implementation needs to satisfy to work with complement crypto.

type LoggedClient

type LoggedClient struct {
	Client
}

func (*LoggedClient) Close

func (c *LoggedClient) Close(t ct.TestLike)

func (*LoggedClient) CurrentAccessToken

func (c *LoggedClient) CurrentAccessToken(t ct.TestLike) string

func (*LoggedClient) DeletePersistentStorage

func (c *LoggedClient) DeletePersistentStorage(t ct.TestLike)

func (*LoggedClient) ForceClose

func (c *LoggedClient) ForceClose(t ct.TestLike)

func (*LoggedClient) IsRoomEncrypted

func (c *LoggedClient) IsRoomEncrypted(t ct.TestLike, roomID string) (bool, error)

func (*LoggedClient) LoadBackup

func (c *LoggedClient) LoadBackup(t ct.TestLike, recoveryKey string) error

func (*LoggedClient) Login

func (c *LoggedClient) Login(t ct.TestLike, opts ClientCreationOpts) error

func (*LoggedClient) MustBackpaginate

func (c *LoggedClient) MustBackpaginate(t ct.TestLike, roomID string, count int)

func (*LoggedClient) MustBackupKeys

func (c *LoggedClient) MustBackupKeys(t ct.TestLike) (recoveryKey string)

func (*LoggedClient) MustGetEvent

func (c *LoggedClient) MustGetEvent(t ct.TestLike, roomID, eventID string) Event

func (*LoggedClient) MustLoadBackup

func (c *LoggedClient) MustLoadBackup(t ct.TestLike, recoveryKey string)

func (*LoggedClient) MustStartSyncing

func (c *LoggedClient) MustStartSyncing(t ct.TestLike) (stopSyncing func())

func (*LoggedClient) SendMessage

func (c *LoggedClient) SendMessage(t ct.TestLike, roomID, text string) (eventID string)

func (*LoggedClient) StartSyncing

func (c *LoggedClient) StartSyncing(t ct.TestLike) (stopSyncing func(), err error)

func (*LoggedClient) TrySendMessage

func (c *LoggedClient) TrySendMessage(t ct.TestLike, roomID, text string) (eventID string, err error)

func (*LoggedClient) WaitUntilEventInRoom

func (c *LoggedClient) WaitUntilEventInRoom(t ct.TestLike, roomID string, checker func(e Event) bool) Waiter

type MockT

type MockT struct {
	TestName string
}

func (*MockT) Error

func (t *MockT) Error(args ...any)

func (*MockT) Errorf

func (t *MockT) Errorf(f string, args ...any)

func (*MockT) Failed

func (t *MockT) Failed() bool

func (*MockT) Fatalf

func (t *MockT) Fatalf(f string, args ...any)

func (*MockT) Helper

func (t *MockT) Helper()

func (*MockT) Logf

func (t *MockT) Logf(f string, args ...any)

func (*MockT) Name

func (t *MockT) Name() string

func (*MockT) Skipf

func (t *MockT) Skipf(f string, args ...any)

type Notification

type Notification struct {
	Event
	HasMentions *bool
}

type Waiter

type Waiter interface {
	// Wait for something to happen, up until the timeout s. If nothing happens,
	// fail the test with the formatted string provided.
	Waitf(t ct.TestLike, s time.Duration, format string, args ...any)
	// Wait for something to happen, up until the timeout s. If nothing happens,
	// return an error with the formatted string provided.
	TryWaitf(t ct.TestLike, s time.Duration, format string, args ...any) error
}