Warp/server/internal/storage/federation.go

package storage

import "context"

// ServerKey is one signing key of another server, as its key server or a
// notary reported it.
type ServerKey struct {
	ServerName string

	// KeyID is the full identifier, algorithm included: "ed25519:abc".
	KeyID string

	// PublicKey is the unpadded base64 key, as it is on the wire.
	PublicKey string

	// ValidUntilTS is how long the server vouched for the key, in
	// milliseconds since the epoch.
	ValidUntilTS int64

	// ExpiredTS is when the server stopped signing with the key, for one
	// it listed as an old_verify_key; zero for a key still in use.
	ExpiredTS int64

	FetchedAtMS int64
}

// The kinds of item in the outbound queue.
const (
	QueueKindPDU = "pdu"
	QueueKindEDU = "edu"
)

// QueuedItem is one PDU or EDU waiting for a destination.
type QueuedItem struct {
	// ID is assigned by Enqueue and orders a destination's items.
	ID int64

	Destination string

	// Kind is QueueKindPDU or QueueKindEDU.
	Kind string

	// RoomID and EventID describe a PDU, for logs and the admin API.
	RoomID  string
	EventID string

	// Payload is the JSON that goes on the wire.
	Payload []byte

	QueuedAtMS int64
}

// Destination is the delivery health of one remote server.
type Destination struct {
	ServerName string

	// Failures is how many sends in a row have failed. Zero is a healthy
	// destination.
	Failures int

	// RetryAtMS is when the next attempt may be made; zero means now.
	RetryAtMS int64

	LastSuccessMS int64
	LastFailureMS int64
	LastError     string
}

// DestinationSummary is a destination with the size of its queue, for the
// admin API.
type DestinationSummary struct {
	Destination

	QueuedPDUs int
	QueuedEDUs int
}

// FederationStore persists what federation needs to survive a restart:
// other servers' keys, the outbound queue, the per-destination backoff and
// the log of inbound transactions.
type FederationStore interface {
	// StoreServerKeys inserts or replaces keys. A key already stored is
	// overwritten with the newer report of it.
	StoreServerKeys(ctx context.Context, keys []ServerKey) error

	// ServerKeys returns the stored keys of a server. An empty keyIDs
	// returns all of them.
	ServerKeys(ctx context.Context, serverName string, keyIDs []string) ([]ServerKey, error)

	// Enqueue adds items to the outbound queue, assigning their IDs.
	Enqueue(ctx context.Context, items []QueuedItem) ([]QueuedItem, error)

	// Queued returns up to limit of a destination's items of one kind,
	// oldest first.
	Queued(ctx context.Context, destination, kind string, limit int) ([]QueuedItem, error)

	// Dequeue removes delivered items.
	Dequeue(ctx context.Context, ids []int64) error

	// QueuedDestinations lists the destinations that have anything queued,
	// which is where a restarted queue picks up.
	QueuedDestinations(ctx context.Context) ([]string, error)

	// Destination reads one destination's delivery health. A server that
	// has never been sent anything comes back as a zero Destination with
	// its name filled in and no error.
	Destination(ctx context.Context, serverName string) (Destination, error)

	// SetDestination records a destination's delivery health.
	SetDestination(ctx context.Context, d Destination) error

	// Destinations lists every destination known to the queue, with its
	// queue depth, ordered by server name.
	Destinations(ctx context.Context) ([]DestinationSummary, error)

	// InboundTransaction returns the response recorded for a transaction
	// already received from origin, and whether there was one.
	InboundTransaction(ctx context.Context, origin, txnID string) ([]byte, bool, error)

	// RecordInboundTransaction stores the response to a transaction so
	// that a retransmission is answered the same way.
	RecordInboundTransaction(ctx context.Context, origin, txnID string, response []byte, atMS int64) error
}