messaging

type EventType uint8

type Media interface {
	ShareIntoChat(ctx context.Context, sharerID *commonpb.UserId, chatID *commonpb.ChatId, blobIDs []*blobpb.BlobId) error
	ResolveRenditions(ctx context.Context, ids []*blobpb.BlobId) (map[string][]*blobpb.Rendition, error)
}

type Message struct {
	ChatID        *commonpb.ChatId
	ID            *messagingpb.MessageId
	SenderID      *commonpb.UserId // nil for system messages
	Content       []*messagingpb.Content
	Timestamp     time.Time
	UnreadSeq     uint64
	EventSequence uint64
	LastEditedTs  time.Time // zero until the message is edited; a delete leaves it untouched
}

type MessageRef struct {
	ChatID    *commonpb.ChatId
	MessageID *messagingpb.MessageId
}

type PointerRef struct {
	ChatID  *commonpb.ChatId
	Members []*commonpb.UserId
}

type Reaction struct {
	Emoji          string
	Count          uint64
	Version        uint64
	Self           *Reactor
	SampleReactors []*Reactor
}

type ReactionSummary struct {
	MessageID *messagingpb.MessageId
	Reactions []*Reaction
}

type Reactor struct {
	UserID    *commonpb.UserId
	ReactedTs time.Time
	Version   uint64
}

type SelfReaction struct {
	MessageID *messagingpb.MessageId
	Emoji     string
	Version   uint64
	ReactedTs time.Time
}

type Sender struct {
	// contains filtered or unexported fields
}

type Server struct {
	messagingpb.UnimplementedMessagingServer
	// contains filtered or unexported fields
}

type Store interface {
	// PutMessage assigns the next gapless message ID for the chat and persists
	// the message, returning the persisted message with its assigned ID and
	// unread sequence.
	//
	// It is idempotent on (chatID, clientMessageID): a retried send with the
	// same client message ID returns the originally persisted message without
	// assigning a new ID. created reports whether this call persisted the
	// message (false on a retry), so callers can skip one-time side effects
	// like pushes.
	//
	// countsTowardUnread controls the unread sequence: when true the message's
	// unread_seq is the previous value + 1; when false it carries the previous
	// value forward (for messages that shouldn't bump anyone's unread count).
	//
	// senderID may be nil to denote a system message.
	PutMessage(
		ctx context.Context,
		chatID *commonpb.ChatId,
		senderID *commonpb.UserId,
		content []*messagingpb.Content,
		ts time.Time,
		clientMessageID *messagingpb.ClientMessageId,
		countsTowardUnread bool,
	) (msg *Message, created bool, err error)

	// EditMessage replaces a message's content with the given content and stamps
	// editedTs as its last-edited time, advances the chat's event-log head, and
	// re-stamps the message's event_sequence to that new head — the message ID and
	// unread_seq are left untouched, so the per-chat ID sequence stays gapless. Like
	// DeleteMessage it advances the event-log head without minting a message ID, so
	// event_sequence diverges from message ID.
	//
	// It is an optimistic-concurrency operation: the edit is applied only if the
	// message's current event_sequence still equals expectedEventSeq. On a mismatch
	// nothing is modified and it returns the message's current state alongside
	// ErrEventSequenceConflict; there is no last-writer-wins path. It returns
	// ErrMessageNotFound if no such message exists. On success it returns the edited
	// message at its new event_sequence.
	EditMessage(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		content []*messagingpb.Content,
		editedTs time.Time,
		expectedEventSeq uint64,
	) (*Message, error)

	// DeleteMessage tombstones a message: it replaces the message's content with a
	// single DeletedContent (carrying deletedTs and deletedBy), advances the chat's
	// event-log head, and re-stamps the message's event_sequence to that new head —
	// the message ID and unread_seq are left untouched, so the per-chat ID sequence
	// stays gapless. This is the first operation that advances the event-log head
	// without minting a message ID, so event_sequence diverges from message ID here.
	//
	// It is an optimistic-concurrency operation: the tombstone is applied only if
	// the message's current event_sequence still equals expectedEventSeq. On a
	// mismatch nothing is modified and it returns the message's current state
	// alongside ErrEventSequenceConflict; there is no last-writer-wins path. It
	// returns ErrMessageNotFound if no such message exists. On success it returns
	// the tombstoned message at its new event_sequence.
	//
	// deletedBy may be nil to denote a system-level deletion (e.g. moderation).
	DeleteMessage(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		deletedBy *commonpb.UserId,
		deletedTs time.Time,
		expectedEventSeq uint64,
	) (*Message, error)

	// GetMessage returns a single message by ID, or ErrMessageNotFound.
	GetMessage(ctx context.Context, chatID *commonpb.ChatId, messageID *messagingpb.MessageId) (*Message, error)

	// MessageExists reports whether a message exists in the chat. It is a
	// lightweight existence check that does not read or decode the message body,
	// for callers (e.g. the reaction read paths) that only need to distinguish a
	// missing message and don't need its content. The read is strongly
	// consistent: it reflects every send that completed before it. Its callers
	// gate an action on a message the user is looking at, and a message just
	// delivered on the stream is one another server committed moments ago —
	// the case a lagging read would report as missing.
	MessageExists(ctx context.Context, chatID *commonpb.ChatId, messageID *messagingpb.MessageId) (bool, error)

	// GetMessages returns a page of messages for a chat ordered by message ID
	// (ascending by default), paged via the provided query options. The paging
	// token's value is the message ID of the last message from the previous
	// page (see PageTokenFromID). Returns an empty result (no error) when the
	// chat has no messages.
	GetMessages(ctx context.Context, chatID *commonpb.ChatId, opts ...database.QueryOption) ([]*Message, error)

	// GetMessagesByRefs returns the messages identified by the given refs that
	// exist, across any number of chats. Refs without a matching message are
	// omitted and duplicate refs collapse. Results are ordered by
	// (chatID, message ID), so refs within a single chat come back ascending by
	// ID. It returns an empty result (no error) when refs is empty.
	//
	// It is the batch read behind the DM feed, where it fetches every chat's last
	// message in one call (one ref per chat). For the single-chat case the caller
	// builds refs from a shared chat ID.
	GetMessagesByRefs(ctx context.Context, refs []MessageRef) ([]*Message, error)

	// GetEventDelta reads up to limit event-log entries with event_sequence in
	// (afterEventSeq, headEventSeq], ascending, and returns the current state of the
	// messages they concern — the page primitive behind GetDelta's catch-up. The
	// event log stores only a thin descriptor per event (message_id, type, ts); each
	// referenced message is joined to its current materialized state here.
	//
	// Superseded events are dropped: when a scanned event's message has since changed
	// again (its current event_sequence is greater than that event's sequence), the
	// stale entry is skipped because a newer event — later in this delta, or, if past
	// head, on the live stream — carries the up-to-date state. So a message appears at
	// most once, at its latest in-range event, in its current state.
	//
	// nextCursor is the highest event_sequence scanned (<= headEventSeq), whether or
	// not it survived the drop — the caller advances its cursor to it so a fully
	// superseded page still makes progress rather than re-reading. It equals
	// afterEventSeq when the range is empty. The log is gapless and read consistently,
	// so advancing by nextCursor never skips an event. limit <= 0 uses the store's
	// default page size.
	GetEventDelta(ctx context.Context, chatID *commonpb.ChatId, afterEventSeq, headEventSeq uint64, limit int) (msgs []*Message, nextCursor uint64, err error)

	// GetLatestEventSequence returns the chat's current head event sequence — the
	// highest event_sequence assigned in the chat, or 0 when the chat has no
	// messages. It bounds GetDelta catch-up: a client whose cursor equals this
	// value is at the head.
	//
	// While every event is a new message (no edits or deletes yet) the event
	// sequence advances in lockstep with the message ID, so this equals the
	// chat's highest message ID. The two are distinct concepts: once edits and
	// deletes advance the event sequence without minting a new message ID, they
	// diverge.
	GetLatestEventSequence(ctx context.Context, chatID *commonpb.ChatId) (uint64, error)

	// GetLatestEventSequencesForChats returns the head event sequence of each of
	// the given chats, keyed by string(chatID.Value). It is the cross-chat batch
	// counterpart to GetLatestEventSequence, used to hydrate Metadata.latest_event_sequence
	// for the DM feed in one call rather than one read per chat. A chat with no
	// messages (head 0) is absent from the map and duplicate chat IDs collapse, so
	// callers must treat a missing key as 0. Returns an empty map (no error) when
	// chatIDs is empty.
	GetLatestEventSequencesForChats(ctx context.Context, chatIDs []*commonpb.ChatId) (map[string]uint64, error)

	// GetPointers returns all delivered/read pointers for a chat. Returns an
	// empty result (no error) when the chat has no pointers.
	GetPointers(ctx context.Context, chatID *commonpb.ChatId) ([]*messagingpb.Pointer, error)

	// GetPointersForChats returns the stored pointers (StoredPointerTypes) for the
	// members named in each ref, keyed by string(chatID.Value). It is the
	// cross-chat batch counterpart to GetPointers, used to hydrate member pointers
	// for the DM feed. Unlike GetPointers it addresses pointers by exact key
	// (chat × member × StoredPointerTypes) in a single batched read rather than
	// scanning each chat's partition; since those are the only types ever stored,
	// this is exhaustive. Chats with no matching pointers are absent from the map
	// and duplicate (chat, member) pairs collapse. Returns an empty map (no error)
	// when refs is empty.
	GetPointersForChats(ctx context.Context, refs []PointerRef) (map[string][]*messagingpb.Pointer, error)

	// AdvancePointer moves a member's pointer of the given type forward to
	// newValue. Pointers are monotonic: a request to move a pointer to a value
	// at or before its current value is a no-op. It always returns the pointer's
	// current state (carrying its last-advanced ts), whether or not this call
	// moved it; the bool reports whether it advanced. The pointer is nil only
	// alongside a non-nil error.
	//
	// It does not verify that newValue references an existing message. Callers
	// with a caller-supplied newValue must check existence first (see
	// MessageExists and the AdvancePointer RPC); callers that already know the
	// message exists — e.g. the sender's own READ pointer right after PutMessage
	// returns the message it just wrote — can advance directly.
	AdvancePointer(
		ctx context.Context,
		chatID *commonpb.ChatId,
		userID *commonpb.UserId,
		pointerType messagingpb.Pointer_Type,
		newValue *messagingpb.MessageId,
	) (*messagingpb.Pointer, bool, error)

	// AddReaction records userID's reaction with emoji on a message and returns
	// the emoji's aggregate after the add. The result goes back to the reactor
	// alone, so unlike the summary reads it is already the caller's view:
	// Self is the caller's own entry, at the version that added their reaction
	// — the new Version on a real add, the earlier one on a re-add — and when:
	// ts on a real add, the original add's time on a re-add (ts is ignored). It
	// is idempotent on (chat, message, emoji, user): a re-add
	// returns the current aggregate with created false and changes nothing.
	// created reports whether this call actually added the reaction (false on a
	// re-add), so callers can skip the broadcast.
	//
	// tooManyTypes is true (with a nil reaction) when adding this emoji would
	// exceed MaxReactionTypesPerMessage distinct emoji on the message; the add is
	// rejected. Re-adding an already-present emoji never trips the cap.
	//
	// It does not verify the message exists or is reactable — the caller checks
	// that first (see Message.IsReactable).
	AddReaction(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		userID *commonpb.UserId,
		emoji string,
		ts time.Time,
	) (reaction *Reaction, created bool, tooManyTypes bool, err error)

	// RemoveReaction removes userID's reaction with emoji from a message. It is
	// idempotent: removing a reaction that isn't present returns removed false and
	// changes nothing. removed reports whether this call actually removed the
	// reaction, so callers can skip the broadcast.
	//
	// reaction is the emoji's aggregate after the removal, with Count possibly 0
	// when the last reactor left (it still carries the advanced Version, which
	// the removal broadcast needs). Self is left nil — which is also
	// the correct overlay for the caller, who just removed their reaction. It is
	// nil only when the emoji has no aggregate at all (a pure no-op).
	RemoveReaction(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		userID *commonpb.UserId,
		emoji string,
	) (reaction *Reaction, removed bool, err error)

	// GetReactionSummary returns the per-emoji aggregates for a single message,
	// one entry per distinct emoji that currently has at least one reactor. The
	// aggregates are shareable: Self is left nil for the caller to
	// overlay (see GetSelfReactions). Returns an empty result (no error) when the
	// message has no reactions.
	//
	// The read is strongly consistent, as every summary read is: it reflects
	// every add and remove that completed before it. A stale count would be
	// harmless — the client keeps the greater version — but a stale *set* is
	// not: a reader who reacts and then refreshes would find their emoji
	// missing, with no version to tell "not yet visible" from "removed", and
	// the strongly consistent self overlay would then have nothing to mark.
	GetReactionSummary(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
	) ([]*Reaction, error)

	// GetReactionSummariesByRefs returns one summary per requested message,
	// deduplicated and ordered by message ID. A message with no reactions (or
	// unknown) is echoed with an empty Reactions slice rather than omitted, so the
	// caller gets an answer for every requested ID. Aggregates are shareable
	// (Self left nil) and the read is strongly consistent (see
	// GetReactionSummary). Returns an empty result (no error) when messageIDs is
	// empty.
	GetReactionSummariesByRefs(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageIDs []*messagingpb.MessageId,
	) ([]*ReactionSummary, error)

	// GetReactionSummaries returns one summary per message in a page of the chat's
	// messages, ordered by message ID and paged via the query options (the paging
	// token is a message ID, as in GetMessages). The page spans messages, not just
	// reacted ones: a message with no reactions is returned with an empty Reactions
	// slice rather than skipped. Aggregates are shareable (Self left
	// false) and the read is strongly consistent (see GetReactionSummary).
	// Returns an empty result (no error) when the page is empty.
	GetReactionSummaries(
		ctx context.Context,
		chatID *commonpb.ChatId,
		opts ...database.QueryOption,
	) ([]*ReactionSummary, error)

	// GetSelfReactions returns every reaction userID currently holds on the given
	// messages of a group, each with the version that added it and when — the
	// per-viewer data behind Reaction.Self and EmojiReaction.self_reactor. It is
	// the viewer's half of a summary read: the aggregates are shareable and
	// leave Self unset, and this answers it for one viewer across a
	// whole page. The read is addressed by the viewer, not by every (message,
	// emoji) on the page, so its cost follows how much the viewer reacted rather
	// than how reacted the page is, and it depends on nothing but the message
	// IDs, so it can run alongside the aggregate read. Message IDs are
	// deduplicated and an unknown ID contributes nothing; the result is in no
	// particular order. Returns an empty result (no error) when messageIDs is
	// empty. The read is strongly consistent: the rows it reads are written and
	// deleted in the add's and remove's own transaction, so it reflects every
	// transition of the viewer's that completed before it.
	//
	// It is for groups only and returns ErrSelfReactionsGroupOnly for a DM. A
	// DM's two members can never outgrow an emoji's sample, so its overlay is
	// read off the aggregates the caller already holds (see
	// Server.applySelfReactions), and a store keeps no per-viewer rows for a DM
	// — a write per reaction that nothing would read.
	GetSelfReactions(
		ctx context.Context,
		chatID *commonpb.ChatId,
		userID *commonpb.UserId,
		messageIDs []*messagingpb.MessageId,
	) ([]SelfReaction, error)

	// GetReactors returns a page of the users who reacted to a message with emoji,
	// most-recent-first (see ReactorLess), paged via the query options (the paging
	// token is a ReactorPageToken). It also returns hasMore, whether further pages
	// remain. Returns an empty result (no error) when the message has no reactors
	// for the emoji. The read is strongly consistent: it reflects every add and
	// remove that completed before it.
	//
	// version is the emoji aggregate's version (Reaction.Version), read BEFORE the
	// page, so the page reflects at least every transition up to it and possibly
	// more. That direction is the safe one: a client holding version may apply live
	// updates for the emoji whose version exceeds it, and any it re-applies are
	// idempotent (an add of a reactor already listed dedupes, a remove of one
	// already absent is a no-op), whereas a version newer than the page would make
	// it drop an update the page is missing. It is 0 when the emoji has no
	// aggregate. A page cannot read the two atomically, so the order of the reads
	// is the contract.
	GetReactors(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		emoji string,
		opts ...database.QueryOption,
	) (reactors []*Reactor, version uint64, hasMore bool, err error)
}