messaging

type EventType uint8

type Media interface {
	ShareIntoChat(ctx context.Context, sharerID *commonpb.UserId, chatID *commonpb.ChatId, blobIDs []*blobpb.BlobId) error
	Resolve(ctx context.Context, ids []*blobpb.BlobId) (map[string]*blobpb.BlobMetadata, 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
	Sequence       uint64
	ReactedBySelf  bool
	SampleReactors []*Reactor
}

type ReactionRef struct {
	MessageID *messagingpb.MessageId
	Emoji     string
}

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

type Reactor struct {
	UserID    *commonpb.UserId
	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.
	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 aggregate is shareable, so
	// ReactedBySelf is left false for the caller to overlay. 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 Sequence, which
	// the removal broadcast needs). ReactedBySelf is left false — 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: ReactedBySelf is left false for the caller to
	// overlay (see GetSelfReactions). Returns an empty result (no error) when the
	// message has no reactions.
	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
	// (ReactedBySelf left false). 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 (ReactedBySelf left
	// false). 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 the subset of refs that userID has reacted to — the
	// per-viewer data behind EmojiReaction.reacted_by_self. The caller derives refs
	// from a summary it already holds, so the store resolves them by exact key in
	// one batched read. Returns an empty result (no error) when refs is empty.
	GetSelfReactions(
		ctx context.Context,
		chatID *commonpb.ChatId,
		userID *commonpb.UserId,
		refs []ReactionRef,
	) ([]ReactionRef, error)

	// GetReactors returns a page of the users who reacted to a message with emoji,
	// most-recent-first, 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.
	//
	// When consistent is true the read is strongly consistent — reflecting every
	// preceding add/remove with no propagation lag — at the cost of scaling less
	// well to large, deeply-paged reactor lists. The flag changes only consistency;
	// the ordering and paging semantics are identical either way.
	GetReactors(
		ctx context.Context,
		chatID *commonpb.ChatId,
		messageID *messagingpb.MessageId,
		emoji string,
		consistent bool,
		opts ...database.QueryOption,
	) (reactors []*Reactor, hasMore bool, err error)
}