api

package
v0.0.0-...-bb8c128 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 6, 2024 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

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 the given user. This function MUST block until one-time keys and device keys have been
	// uploaded to the server. Failure to block will result in flakey tests as other users may not
	// encrypt for this Client due to not detecting keys for the Client.
	Login(t ct.TestLike, opts ClientCreationOpts) error
	// 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)
	// InviteUser attempts to invite the given user into the given room.
	InviteUser(t ct.TestLike, roomID, userID string) error
	// SendMessage sends the given text as an encrypted/unencrypted message in the room, depending
	// if the room is encrypted or not. Returns the event ID of the sent event, so MUST BLOCK until the event has been sent.
	// If the event cannot be sent, returns an error.
	SendMessage(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. Returns an error if there was a problem backpaginating.
	// Getting to the beginning of the room is not an error condition.
	Backpaginate(t ct.TestLike, roomID string, count int) error
	// GetEvent will return the client's view of this event, or returns an error if the event cannot be found.
	GetEvent(t ct.TestLike, roomID, eventID string) (*Event, error)
	// BackupKeys will backup E2EE keys, else return an error.
	BackupKeys(t ct.TestLike) (recoveryKey string, err error)
	// 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.
	// Clients should implement this AS IF they received a push notification.
	GetNotification(t ct.TestLike, roomID, eventID string) (*Notification, error)
	// ListenForVerificationRequests will listen for incoming verification requests.
	// See RequestOwnUserVerification for information on the stages.
	ListenForVerificationRequests(t ct.TestLike) chan VerificationStage
	// RequestOwnUserVerification tries to verify this device with another logged in device.
	//
	// Returns a stream of verification stages. Callers should listen on this stream
	// (with appropriate timeouts if no change has been seen) and then type switch to
	// determine what the current stage is. The type switched interface will contain only
	// the valid state transitions for that stage. E.g:
	//    for stage := range client.RequestOwnUserVerification(t) {
	//        switch stg := stage.(type) {
	//            case api.VerificationStageReady:
	//               // ...
	//        }
	//    }
	// The channel is closed when the verification process reaches a terminal state.
	RequestOwnUserVerification(t ct.TestLike) chan VerificationStage
	// 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. Clients are not limited to this interface, and can test functionality specific to their client by type casting at runtime.

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

	// Required for rust clients. The URL of the sliding sync proxy.
	SlidingSyncURL string
	// Optional. Set this to login with this device ID.
	DeviceID string

	// A hint to the client implementation that persistent storage is required. Clients may ignore
	// this flag and always use persistence.
	PersistentStorage bool

	// A map containing any client-specific creation options, for use for client-specific tests.
	// Any options in this map MUST BE SERIALISABLE as they may be sent over RPC boundaries.
	ExtraOpts map[string]any

	// 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

func (*ClientCreationOpts) Combine 

func (o *ClientCreationOpts) Combine(other *ClientCreationOpts)

Combine the other opts into this set of opts.

func (*ClientCreationOpts) GetExtraOption 

func (o *ClientCreationOpts) GetExtraOption(key string, defaultValue any) any

GetExtraOption is a safe way to get an extra option from ExtraOpts, with a default value if the key does not exist.

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) Backpaginate 

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

func (*LoggedClient) BackupKeys 

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

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) GetEvent 

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

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) SendMessage 

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

func (*LoggedClient) StartSyncing 

func (c *LoggedClient) StartSyncing(t ct.TestLike) (stopSyncing func(), 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 TestClient 

type TestClient interface {
	Client
	// MustStartSyncing is StartSyncing but fails the test on error.
	MustStartSyncing(t ct.TestLike) (stopSyncing func())
	// MustLoadBackup is LoadBackup but fails the test on error.
	MustLoadBackup(t ct.TestLike, recoveryKey string)
	// MustSendMessage is SendMessage but fails the test on error.
	MustSendMessage(t ct.TestLike, roomID, text string) (eventID string)
	// MustGetEvent is GetEvent but fails the test on error.
	MustGetEvent(t ct.TestLike, roomID, eventID string) *Event
	// MustBackupKeys is BackupKeys but fails the test on error.
	MustBackupKeys(t ct.TestLike) (recoveryKey string)
	// MustBackpaginate is Backpaginate but fails the test on error.
	MustBackpaginate(t ct.TestLike, roomID string, count int)
}

TestClient is a Client with extra helper functions added to make writing tests easier. Client implementations are not expected to implement these helper functions, and are instead composed together by the test rig itself.

func NewTestClient 

func NewTestClient(c Client) TestClient

NewTestClient wraps a Client implementation with helper functions which tests can use.

type VerificationContainer 

type VerificationContainer struct {
	VReq           VerificationRequest
	VData          VerificationData
	VState         VerificationState
	SendReady      func()
	SendStart      func(method string)
	SendCancel     func()
	SendDone       func()
	SendTransition func()
	SendApprove    func()
	SendDecline    func()
	Mutex          *sync.Mutex
}

VerificationContainer is a helper struct for client implementations. It implements all verification stages, so can be returned at each stage. The container is never exposed directly in tests, as interfaces hide invalid state transitions.

func (*VerificationContainer) Modify 

func (c *VerificationContainer) Modify(fn func(cc *VerificationContainer))

func (*VerificationContainer) Stage 

func (c *VerificationContainer) Stage(stageEnum VerificationStageEnum) VerificationStage

type VerificationData 

type VerificationData struct {
	Emojis   []string
	Decimals []uint16
}

type VerificationRequest 

type VerificationRequest struct {
	TxnID            string
	SenderUserID     string
	SenderDeviceID   string
	ReceiverUserID   string
	ReceiverDeviceID string
}

type VerificationStage 

type VerificationStage interface{}

type VerificationStageCancelled 

type VerificationStageCancelled interface {
}

func NewVerificationStageCancelled 

func NewVerificationStageCancelled(c *VerificationContainer) VerificationStageCancelled

type VerificationStageDone 

type VerificationStageDone interface {
	VerificationState() VerificationState
}

func NewVerificationStageDone 

func NewVerificationStageDone(c *VerificationContainer) VerificationStageDone

type VerificationStageEnum 

type VerificationStageEnum int
const (
	VerificationStageEnumRequested VerificationStageEnum = iota
	VerificationStageEnumRequestedReceiver
	VerificationStageEnumReady
	VerificationStageEnumStart
	VerificationStageEnumTransitioned
	VerificationStageEnumDone
	VerificationStageEnumCancelled
)

type VerificationStageReady 

type VerificationStageReady interface {
	Start(method string)
	Cancel()
}

func NewVerificationStageReady 

func NewVerificationStageReady(c *VerificationContainer) VerificationStageReady

type VerificationStageRequested 

type VerificationStageRequested interface {
	Request() VerificationRequest
	Cancel()
}

func NewVerificationStageRequested 

func NewVerificationStageRequested(c *VerificationContainer) VerificationStageRequested

type VerificationStageRequestedReceiver 

type VerificationStageRequestedReceiver interface {
	Request() VerificationRequest
	Cancel()
	Ready()
}

func NewVerificationStageRequestedReceiver 

func NewVerificationStageRequestedReceiver(c *VerificationContainer) VerificationStageRequestedReceiver

type VerificationStageStart 

type VerificationStageStart interface {
	Transition()
	Cancel()
}

func NewVerificationStageStart 

func NewVerificationStageStart(c *VerificationContainer) VerificationStageStart

type VerificationStageTransitioned 

type VerificationStageTransitioned interface {
	Done()
	VerificationData() VerificationData
	Approve()
	Decline()
	Cancel()
	Transition()
}

func NewVerificationStageTransitioned 

func NewVerificationStageTransitioned(c *VerificationContainer) VerificationStageTransitioned

type VerificationState 

type VerificationState string
var (
	VerificationStateVerified   VerificationState = "verified"
	VerificationStateUnverified VerificationState = "unverified"
	VerificationStateUnknown    VerificationState = "unknown"
)

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
}

Source Files

View all Source files

Directories

Path Synopsis
js
chrome
package chrome provides helper functions to execute JS in a Chrome browser
 package chrome provides helper functions to execute JS in a Chrome browser
package langs contains language binding implementations
 package langs contains language binding implementations

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.