federation

package
v0.0.0-...-7485d36 Latest Latest
Warning

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

 Go to latest Published: Jan 31, 2025 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

package federation is an EXPERIMENTAL set of functions for creating mock federation servers, for testing over federation. It is marked as EXPERIMENTAL as the API may break without warning.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func HandleDirectoryLookups 

func HandleDirectoryLookups() func(*Server)

EXPERIMENTAL HandleDirectoryLookups will automatically return room IDs for any aliases present on this server.

func HandleEventAuthRequests 

func HandleEventAuthRequests() func(*Server)

EXPERIMENTAL HandleEventAuthRequests is an option which will process GET /_matrix/federation/v1/event_auth/{roomId}/{eventId} requests universally when requested.

func HandleEventRequests 

func HandleEventRequests() func(*Server)

EXPERIMENTAL HandleEventRequests is an option which will process GET /_matrix/federation/v1/event/{eventId} requests universally when requested.

func HandleInviteRequests 

func HandleInviteRequests(inviteCallback func(gomatrixserverlib.PDU)) func(*Server)

EXPERIMENTAL HandleInviteRequests is an option which makes the server process invite requests.

inviteCallback is a callback function that if non-nil will be called and passed the incoming invite event

func HandleKeyRequests 

func HandleKeyRequests() func(*Server)

EXPERIMENTAL HandleKeyRequests is an option which will process GET /_matrix/key/v2/server requests universally when requested.

func HandleMakeSendJoinRequests 

func HandleMakeSendJoinRequests() func(*Server)

EXPERIMENTAL HandleMakeSendJoinRequests is an option which will process make_join and send_join requests for rooms which are present in this server. To add a room to this server, see Server.MustMakeRoom. No checks are done to see whether join requests are allowed or not. If you wish to test that, write your own test.

func HandleMediaRequests 

func HandleMediaRequests(mediaIds map[string]func(w http.ResponseWriter)) func(*Server)

EXPERIMENTAL HandleMediaRequests is an option which will process /_matrix/media/v1/download/* using the provided map as a way to do so. The key of the map is the media ID to be handled.

func HandlePartialStateMakeSendJoinRequests 

func HandlePartialStateMakeSendJoinRequests() func(*Server)

HandlePartialStateMakeSendJoinRequests is similar to HandleMakeSendJoinRequests, but expects a partial-state join.

func HandleTransactionRequests 

func HandleTransactionRequests(pduCallback func(gomatrixserverlib.PDU), eduCallback func(gomatrixserverlib.EDU)) func(*Server)

EXPERIMENTAL HandleTransactionRequests is an option which will process GET /_matrix/federation/v1/send/{transactionID} requests universally when requested. pduCallback and eduCallback are functions that if non-nil will be called and passed each PDU or EDU event received in the transaction. Callbacks will be fired AFTER the event has been stored onto the respective ServerRoom.

func MakeJoinRequestsHandler 

func MakeJoinRequestsHandler(s *Server, w http.ResponseWriter, req *http.Request)

EXPERIMENTAL MakeJoinRequestsHandler is the http.Handler implementation for the make_join part of HandleMakeSendJoinRequests.

func MakeRespMakeJoin 

func MakeRespMakeJoin(s *Server, room *ServerRoom, userID string) (resp fclient.RespMakeJoin, err error)

EXPERIMENTAL MakeRespMakeJoin makes the response for a /make_join request, without verifying any signatures or dealing with HTTP responses itself.

func MakeRespMakeKnock 

func MakeRespMakeKnock(s *Server, room *ServerRoom, userID string) (resp fclient.RespMakeKnock, err error)

EXPERIMENTAL MakeRespMakeKnock makes the response for a /make_knock request, without verifying any signatures or dealing with HTTP responses itself.

func SendJoinRequestsHandler 

func SendJoinRequestsHandler(s *Server, w http.ResponseWriter, req *http.Request, expectPartialState bool, omitServersInRoom bool)

EXPERIMENTAL SendJoinRequestsHandler is the http.Handler implementation for the send_join part of HandleMakeSendJoinRequests.

expectPartialState should be true if we should expect the incoming send_join request to use the partial_state flag, per MSC3706. In that case, we reply with only the critical subset of the room state.

omitServersInRoom should be false to respond to partial_state joins with the complete list of servers in the room. When omitServersInRoom is true, a misbehaving server is simulated and only the current server is returned to the joining server.

func SupportedRoomVersions 

func SupportedRoomVersions() []gomatrixserverlib.RoomVersion

SupportedRoomVersions is a convenience method which returns a list of the room versions supported by gomatrixserverlib.

Types

type Event 

type Event struct {
	Type     string
	Sender   string
	StateKey *string
	Content  map[string]interface{}

	Unsigned map[string]interface{}
	// The events needed to authenticate this event.
	// This can be either []EventReference for room v1/v2, or []string for room v3 onwards.
	// If it is left at nil, MustCreateEvent will populate it automatically based on the room state.
	AuthEvents interface{}
	// The prev events of the event if we want to override or falsify them.
	// If it is left at nil, MustCreateEvent will populate it automatically based on the forward extremities.
	PrevEvents interface{}
	// If this is a redaction, the event that it redacts
	Redacts string
}

func InitialRoomEvents 

func InitialRoomEvents(roomVer gomatrixserverlib.RoomVersion, creator string) []Event

InitialRoomEvents returns the initial set of events that get created when making a room.

type FederationDeployment 

type FederationDeployment interface {
	GetConfig() *config.Complement
	RoundTripper() http.RoundTripper
}

Subset of Deployment used in federation

type Server 

type Server struct {

	// Default: true
	UnexpectedRequestsAreErrors bool

	Priv  ed25519.PrivateKey
	KeyID gomatrixserverlib.KeyID
	// contains filtered or unexported fields
}

EXPERIMENTAL Server represents a federation server

func NewServer 

func NewServer(t ct.TestLike, deployment FederationDeployment, opts ...func(*Server)) *Server

EXPERIMENTAL NewServer creates a new federation server with configured options.

func (*Server) DoFederationRequest 

func (s *Server) DoFederationRequest(
	ctx context.Context,
	t ct.TestLike,
	deployment FederationDeployment,
	req fclient.FederationRequest) (*http.Response, error)

DoFederationRequest signs and sends an arbitrary federation request from this server, and returns the response.

The requests will be routed according to the deployment map in `deployment`.

func (*Server) FederationClient 

func (s *Server) FederationClient(deployment FederationDeployment) fclient.FederationClient

FederationClient returns a client which will sign requests using this server's key.

The requests will be routed according to the deployment map in `deployment`, which satisfies the RoundTripper interface.

func (*Server) Listen 

func (s *Server) Listen() (cancel func())

Listen for federation server requests - call the returned function to gracefully close the server.

func (*Server) MakeAliasMapping 

func (s *Server) MakeAliasMapping(aliasLocalpart, roomID string) string

MakeAliasMapping will create a mapping of room alias to room ID on this server. Returns the alias. If this is the first time calling this function, a directory lookup handler will be added to handle alias requests over federation.

func (*Server) MustCreateEvent 

func (s *Server) MustCreateEvent(t ct.TestLike, room *ServerRoom, ev Event) gomatrixserverlib.PDU

MustCreateEvent will create and sign a new latest event for the given room. It does not insert this event into the room however. See ServerRoom.AddEvent for that.

func (*Server) MustJoinRoom 

func (s *Server) MustJoinRoom(t ct.TestLike, deployment FederationDeployment, remoteServer spec.ServerName, roomID string, userID string, partialState ...bool) *ServerRoom

MustJoinRoom will make the server send a make_join and a send_join to join a room It returns the resultant room.

func (*Server) MustLeaveRoom 

func (s *Server) MustLeaveRoom(t ct.TestLike, deployment FederationDeployment, remoteServer spec.ServerName, roomID string, userID string)

Leaves a room. If this is rejecting an invite then a make_leave request is made first, before send_leave.

func (*Server) MustMakeRoom 

func (s *Server) MustMakeRoom(t ct.TestLike, roomVer gomatrixserverlib.RoomVersion, events []Event) *ServerRoom

MustMakeRoom will add a room to this server so it is accessible to other servers when prompted via federation. The `events` will be added to this room. Returns the created room.

func (*Server) MustSendTransaction 

func (s *Server) MustSendTransaction(t ct.TestLike, deployment FederationDeployment, destination string, pdus []json.RawMessage, edus []gomatrixserverlib.EDU)

MustSendTransaction sends the given PDUs/EDUs to the target destination, returning an error if the /send fails or if the response contains an error for any sent PDUs. Times out after 10 seconds.

func (*Server) Mux 

func (s *Server) Mux() *mux.Router

Mux returns this server's router so you can attach additional paths.

func (*Server) SendFederationRequest 

func (s *Server) SendFederationRequest(
	ctx context.Context,
	t ct.TestLike,
	deployment FederationDeployment,
	req fclient.FederationRequest,
	resBody interface{},
) error

SendFederationRequest signs and sends an arbitrary federation request from this server.

The requests will be routed according to the deployment map in `deployment`.

func (*Server) ServerName 

func (s *Server) ServerName() string

Return the server name of this federation server. Only valid AFTER calling Listen() - doing so before will produce an error.

It is not supported to call ServerName() before Listen() because Listen() modifies the server name. Listen() will select a random OS-provided high-numbered port to listen on, which then needs to be retrofitted into the server name so containers know how to route to it.

func (*Server) UserID 

func (s *Server) UserID(localpart string) string

UserID returns the complete user ID for the given localpart

func (*Server) ValidFederationRequest 

func (s *Server) ValidFederationRequest(t ct.TestLike, handler func(fr *fclient.FederationRequest, pathParams map[string]string) util.JSONResponse) http.HandlerFunc

ValidFederationRequest is a wrapper around http.HandlerFunc which automatically validates the incoming federation request and supports sending back JSON. Fails the test if the request is not valid.

type ServerRoom 

type ServerRoom struct {
	Version            gomatrixserverlib.RoomVersion
	RoomID             string
	State              map[string]gomatrixserverlib.PDU
	StateMutex         sync.RWMutex
	Timeline           []gomatrixserverlib.PDU
	TimelineMutex      sync.RWMutex
	ForwardExtremities []string
	Depth              int64
	// contains filtered or unexported fields
}

EXPERIMENTAL ServerRoom represents a room on this test federation server

func (*ServerRoom) AddEvent 

func (r *ServerRoom) AddEvent(ev gomatrixserverlib.PDU)

AddEvent adds a new event to the timeline, updating current state if it is a state event. Updates depth and forward extremities.

func (*ServerRoom) AllCurrentState 

func (r *ServerRoom) AllCurrentState() (events []gomatrixserverlib.PDU)

AllCurrentState returns all the current state events

func (*ServerRoom) AuthChain 

func (r *ServerRoom) AuthChain() (chain []gomatrixserverlib.PDU)

AuthChain returns all auth events for all events in the current state TODO: recursively

func (*ServerRoom) AuthChainForEvents 

func (r *ServerRoom) AuthChainForEvents(events []gomatrixserverlib.PDU) (chain []gomatrixserverlib.PDU)

AuthChainForEvents returns all auth events for all events in the given state

func (*ServerRoom) AuthEvents 

func (r *ServerRoom) AuthEvents(sn gomatrixserverlib.StateNeeded) (eventIDs []string)

AuthEvents returns the state event IDs of the auth events which authenticate this event

func (*ServerRoom) CurrentState 

func (r *ServerRoom) CurrentState(evType, stateKey string) gomatrixserverlib.PDU

CurrentState returns the state event for the given (type, state_key) or nil.

func (*ServerRoom) EventIDsOrReferences 

func (r *ServerRoom) EventIDsOrReferences(events []gomatrixserverlib.PDU) (refs []interface{})

EventIDsOrReferences converts a list of events into a list of EventIDs or EventReferences, depending on the room version

func (*ServerRoom) GetEventInTimeline 

func (r *ServerRoom) GetEventInTimeline(eventID string) (gomatrixserverlib.PDU, bool)

Fetches the event with given event ID from the room timeline.

func (*ServerRoom) MustHaveMembershipForUser 

func (r *ServerRoom) MustHaveMembershipForUser(t ct.TestLike, userID, wantMembership string)

Check that the user currently has the membership provided in this room. Fails the test if not.

func (*ServerRoom) ServersInRoom 

func (r *ServerRoom) ServersInRoom() (servers []string)

ServersInRoom gets all servers currently joined to the room

func (*ServerRoom) WaiterForEvent 

func (r *ServerRoom) WaiterForEvent(eventID string) *helpers.Waiter

WaiterForEvent creates a Waiter which waits until the given event ID is added to the room. This can be used as a synchronisation point to wait until the server under test has sent a given PDU in a /send transaction to the Complement server. This is the equivalent to listening for the PDU in the /send transaction and then unblocking the Waiter. Note that calling this function doesn't actually block. Call .Wait(time.Duration) on the waiter to block.

Note: you must still add HandleTransactionRequests(nil,nil) to your server for the server to automatically add events to the room.

Source Files

View all Source files

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.