Warp/server/internal/storage/rooms.go

package storage

import (
	"context"
	"errors"
)

// Errors the room store returns for cases a caller has to tell apart.
var (
	// ErrNoSuchRoom is returned for a room this server does not know.
	ErrNoSuchRoom = errors.New("no such room")

	// ErrRoomExists is returned by CreateRoom for a room ID already taken.
	// It can only happen through a room ID collision, which for a room
	// version 12 room would mean two identical create events.
	ErrRoomExists = errors.New("room already exists")

	// ErrNoSuchEvent is returned for an event ID the room store does not
	// hold.
	ErrNoSuchEvent = errors.New("no such event")

	// ErrNoSuchAlias is returned for an unknown room alias.
	ErrNoSuchAlias = errors.New("no such room alias")

	// ErrAliasExists is returned by CreateAlias for an alias already
	// pointing somewhere.
	ErrAliasExists = errors.New("room alias already exists")
)

// Room is one room this server takes part in.
//
// The version is fixed when the room is created and is what every later read
// needs first: an event cannot even be parsed without knowing the rules it
// was written under.
type Room struct {
	ID string

	// Version is the room version identifier, e.g. "11".
	Version string

	// Creator is the full user ID that sent the m.room.create event.
	Creator string

	// Published reports whether the room is in this server's public room
	// directory.
	Published bool

	CreatedAtMS int64
}

// NewRoom describes a room to create. The create event itself is written by
// the same Write call that appends any other event.
type NewRoom struct {
	ID          string
	Version     string
	Creator     string
	Published   bool
	CreatedAtMS int64
}

// RoomProfile is the denormalised view of a room's state that a room
// listing is searched and ordered by.
//
// It is all derivable from the room's current state, and is stored anyway:
// the public room directory sorts every published room by member count and
// pages the result, which cannot be done by reading each room's state in
// turn. The roomserver recomputes it whenever one of the state events behind
// it changes and hands it to Write; the store only keeps it, because
// knowing that m.room.name means a name is the roomserver's business.
//
// JoinedMembers is the exception: the store maintains it itself, by counting
// the current-state rows whose membership is "join".
type RoomProfile struct {
	Name           string
	Topic          string
	AvatarURL      string
	CanonicalAlias string

	JoinRule          string
	HistoryVisibility string
	GuestAccess       string

	// RoomType is m.room.create's content.type: empty for a normal room,
	// "m.space" for a space.
	RoomType string
}

// StateEntry is one piece of room state and the event that holds it.
type StateEntry struct {
	Type     string
	StateKey string
	EventID  string

	// Membership is the membership value of an m.room.member entry, and
	// empty on every other kind of state. It travels with the entry so that
	// the store can keep "who is joined to this room" answerable with an
	// index instead of by parsing event JSON.
	Membership string
}

// StoredEvent is an event as the room store holds it: the canonical JSON
// plus the columns worth indexing separately.
//
// JSON is the authority. The other fields are projections of it, written out
// so that the store can answer "the members of this room" or "events in
// stream order" without parsing every row.
type StoredEvent struct {
	RoomID  string
	EventID string
	Type    string

	// StateKey is nil for a non-state event. The empty string is a
	// perfectly good state key, which is why this is a pointer.
	StateKey *string

	Sender         string
	Depth          int64
	OriginServerTS int64

	// JSON is the event as canonical JSON, exactly as it was signed.
	JSON []byte

	// StreamOrdering is this server's own monotonic position for the event:
	// the order it was persisted in, which is the order /sync and /messages
	// hand events to clients.
	StreamOrdering int64

	// RedactedBy is the event ID of the redaction that applies to this
	// event, or empty. The JSON is rewritten in place when a redaction is
	// applied, so a redacted event is already stripped on the way out; this
	// field is what lets unsigned.redacted_because be filled in.
	RedactedBy string
}

// IsState reports whether the event is a state event.
func (e StoredEvent) IsState() bool { return e.StateKey != nil }

// TransactionRef records a client transaction ID against the event it
// produced, so that a retried PUT returns the first event rather than
// sending a second one.
type TransactionRef struct {
	Localpart string
	DeviceID  string
	TxnID     string
}

// RoomWrite is one event and everything its arrival changes, written in a
// single transaction.
//
// Persisting an event is never just an insert: it moves the room's forward
// extremities, it may replace a piece of current state, and it may strip an
// earlier event. Splitting that across calls would leave a window in which
// the room's current state disagrees with its events, so the whole lot goes
// down together.
type RoomWrite struct {
	// Event is the event being appended. Its StreamOrdering is assigned by
	// the store and returned.
	Event StoredEvent

	// StateBefore is the room state the event was authorised against: the
	// full state of the room as of its prev_events. It is stored as a
	// deduplicated snapshot, so appending a message to a quiet room adds no
	// state rows at all.
	StateBefore []StateEntry

	// StateDelta are the pieces of current state this event changes — for
	// an ordinary state event, the single tuple it writes. It is empty for
	// an event that changes no state.
	StateDelta []StateEntry

	// StateDeltaIsWholeState says that StateDelta is the room's entire new
	// current state, and that any tuple not in it must be removed. State
	// resolution across a forked room produces such a result; a single
	// state event does not, and rewriting the whole of a large room's state
	// on every join would make filling a room quadratic.
	StateDeltaIsWholeState bool

	// Profile updates the denormalised room listing columns. It is nil when
	// this event changes none of them.
	Profile *RoomProfile

	// Extremities replaces the room's forward extremities. For a locally
	// created event that is the event itself, since it descends from every
	// extremity there was.
	Extremities []string

	// Transaction, when set, records the client transaction ID this event
	// came from.
	Transaction *TransactionRef

	// Redacts is the event ID this event redacts, when the redaction is to
	// be applied. RedactedJSON is the target's redacted form, which
	// replaces the stored JSON.
	Redacts      string
	RedactedJSON []byte
}

// RoomAlias is a local alias and the room it points at.
type RoomAlias struct {
	Alias  string
	RoomID string

	// Creator is the full user ID that created the alias.
	Creator string

	CreatedAtMS int64
}

// MembershipEntry is one member of a room.
type MembershipEntry struct {
	UserID     string
	Membership string
	EventID    string
}

// RoomFilter narrows and pages a room listing.
type RoomFilter struct {
	// Search matches a substring of the room ID, name, topic or canonical
	// alias, case-insensitively. Empty matches everything.
	Search string

	// Limit caps the returned rows; 0 means the store's own default.
	Limit int

	// Offset skips rows, for paging.
	Offset int
}

// RoomSummary is a room as a listing shows it: the room row, its
// denormalised state and its member count.
type RoomSummary struct {
	Room
	RoomProfile

	// JoinedMembers is how many members of the room are joined.
	JoinedMembers int
}

// RoomStats are the room counts the admin dashboard shows.
type RoomStats struct {
	Rooms     int
	Published int
	Events    int
}

// RoomStore persists rooms, their events and their state: the storage half
// of the roomserver component.
//
// Every method takes identifiers the caller has already validated. The store
// interprets nothing: it does not know the authorisation rules, it does not
// know which room versions exist, and it never parses an event. What it
// guarantees is that a room's events, its state and its extremities are only
// ever seen in a consistent set.
type RoomStore interface {
	// CreateRoom inserts the room row, returning ErrRoomExists when the ID
	// is taken.
	CreateRoom(ctx context.Context, room NewRoom) error

	// Room reads one room, returning ErrNoSuchRoom if it is absent.
	Room(ctx context.Context, roomID string) (Room, error)

	// Write appends one event and applies everything it changes. It returns
	// the stream ordering the event was given.
	Write(ctx context.Context, w RoomWrite) (int64, error)

	// Event reads one event of a room, returning ErrNoSuchEvent if it is
	// absent.
	Event(ctx context.Context, roomID, eventID string) (StoredEvent, error)

	// EventsByID reads events by ID within one room. Unknown IDs are left
	// out rather than reported: state resolution needs exactly that
	// behaviour for events this server does not have.
	EventsByID(ctx context.Context, roomID string, eventIDs []string) ([]StoredEvent, error)

	// CurrentState returns the room's resolved current state.
	CurrentState(ctx context.Context, roomID string) ([]StateEntry, error)

	// CurrentStateEvents returns the events behind the room's current
	// state, which is what the authorisation rules are run against.
	CurrentStateEvents(ctx context.Context, roomID string) ([]StoredEvent, error)

	// CurrentStateEvent returns one piece of current state, or
	// ErrNoSuchEvent when the room has no such state.
	CurrentStateEvent(ctx context.Context, roomID, eventType, stateKey string) (StoredEvent, error)

	// StateBefore returns the state snapshot recorded against an event: the
	// state of the room as of that event's prev_events.
	StateBefore(ctx context.Context, roomID, eventID string) ([]StateEntry, error)

	// Extremities returns the room's forward extremities, which are the
	// prev_events of the next event to be sent.
	Extremities(ctx context.Context, roomID string) ([]StoredEvent, error)

	// Members returns the m.room.member events of a room. memberships
	// filters by membership value; empty returns every member event,
	// including the users who have left.
	Members(ctx context.Context, roomID string, memberships []string) ([]StoredEvent, error)

	// MembershipEntries returns the memberships of a room without the event
	// bodies, which is what /joined_members needs.
	MembershipEntries(ctx context.Context, roomID string, memberships []string) ([]MembershipEntry, error)

	// Membership returns a user's membership in a room and the event that
	// set it. A user who was never in the room gets an empty membership and
	// no error: "never joined" and "left" are the same answer to every rule
	// that asks.
	Membership(ctx context.Context, roomID, userID string) (MembershipEntry, error)

	// RoomsForUser lists the rooms a user has one of the given memberships
	// in, ordered by room ID.
	RoomsForUser(ctx context.Context, userID string, memberships []string) ([]string, error)

	// MembershipsForUser is RoomsForUser with the membership and the
	// position of the event that set it: one query for everything a sync
	// needs to know about where a user stands.
	MembershipsForUser(ctx context.Context, userID string, memberships []string) ([]SyncMembership, error)

	// UserMembershipEvents returns every m.room.member event of one user in
	// one room, oldest first.
	//
	// It is how far back a user's own view of a room reaches: a user who
	// joined, left and rejoined has several spans, and only their own
	// membership events say where each one began. There is one row per
	// membership change of one user in one room, so this stays small
	// however busy the room is.
	UserMembershipEvents(ctx context.Context, roomID, userID string) ([]StoredEvent, error)

	// MaxStreamOrdering returns the top of this server's event stream, or 0
	// for a server that has persisted no events.
	MaxStreamOrdering(ctx context.Context) (int64, error)

	// Timeline reads one window of a room's event stream. See
	// TimelineRequest: the bounds are exclusive and the limit is required.
	Timeline(ctx context.Context, req TimelineRequest) ([]StoredEvent, error)

	// RoomsWithEvents returns the subset of roomIDs that have an event
	// after from and at or before to.
	//
	// It is what keeps an incremental sync down to one query for the common
	// case of nothing having happened: a user in two hundred rooms would
	// otherwise need two hundred timeline reads to find that out.
	RoomsWithEvents(ctx context.Context, roomIDs []string, from, to int64) ([]string, error)

	// StateAtStream returns the room's state as of a stream position: the
	// state after the last event at or before pos.
	//
	// It answers the two questions current state cannot. A user who has
	// left sees the room as it was when they left, and a sync with a gap in
	// it has to say which state changed inside that gap.
	StateAtStream(ctx context.Context, roomID string, pos int64) ([]StateEntry, error)

	// TransactionEvent returns the event a client transaction ID already
	// produced, or ErrNoSuchEvent when this is the first time it is seen.
	TransactionEvent(ctx context.Context, ref TransactionRef) (string, error)

	// CreateAlias points an alias at a room, returning ErrAliasExists when
	// the alias is taken.
	CreateAlias(ctx context.Context, alias RoomAlias) error

	// DeleteAlias removes an alias, returning ErrNoSuchAlias if it is
	// absent.
	DeleteAlias(ctx context.Context, alias string) error

	// Alias resolves an alias, returning ErrNoSuchAlias if it is absent.
	// The creator comes back with it because the permission check on
	// deleting an alias is partly about who made it.
	Alias(ctx context.Context, alias string) (RoomAlias, error)

	// AliasesForRoom lists the local aliases pointing at a room, sorted.
	AliasesForRoom(ctx context.Context, roomID string) ([]string, error)

	// SetPublished adds or removes a room from the public room directory,
	// returning ErrNoSuchRoom for a room that does not exist.
	SetPublished(ctx context.Context, roomID string, published bool) error

	// PublishedRooms returns a page of the public room directory ordered by
	// descending joined-member count, plus the total number of published
	// rooms matching the filter.
	PublishedRooms(ctx context.Context, filter RoomFilter) ([]RoomSummary, int, error)

	// ListRooms returns a page of every room for the admin API, plus the
	// total matching the filter.
	ListRooms(ctx context.Context, filter RoomFilter) ([]RoomSummary, int, error)

	// RoomSummary returns one room with its denormalised state, returning
	// ErrNoSuchRoom if it is absent.
	RoomSummary(ctx context.Context, roomID string) (RoomSummary, error)

	// PurgeRoom deletes a room and everything belonging to it, returning
	// ErrNoSuchRoom for a room that does not exist. It is the admin API's
	// last resort and has no undo.
	PurgeRoom(ctx context.Context, roomID string) error

	// RoomStats returns the aggregate counts for the admin dashboard.
	RoomStats(ctx context.Context) (RoomStats, error)
}