messaging

type Message struct {
	ChatID    *commonpb.ChatId
	ID        *messagingpb.MessageId
	SenderID  *commonpb.UserId // nil for system messages
	Content   []*messagingpb.Content
	Timestamp time.Time
	UnreadSeq uint64
}

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

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

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.
	//
	// 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,
	) (*Message, error)

	// GetMessage returns a single message by ID, or ErrMessageNotFound.
	GetMessage(ctx context.Context, chatID *commonpb.ChatId, messageID *messagingpb.MessageId) (*Message, 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)

	// 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 returns ErrMessageNotFound
	// if newValue does not reference an existing message in the chat. The bool
	// return reports whether the pointer advanced.
	AdvancePointer(
		ctx context.Context,
		chatID *commonpb.ChatId,
		userID *commonpb.UserId,
		pointerType messagingpb.Pointer_Type,
		newValue *messagingpb.MessageId,
	) (bool, error)

	// AdvancePointerUnchecked is AdvancePointer for a newValue the caller already
	// knows references an existing message — e.g. the sender's own READ pointer
	// right after PutMessage returns the message it just wrote. It skips the
	// existence check (and the read backing it), saving a round trip; the
	// monotonic forward-only behavior is otherwise identical to AdvancePointer.
	// It must not be used with a caller-supplied newValue, whose existence is not
	// guaranteed.
	AdvancePointerUnchecked(
		ctx context.Context,
		chatID *commonpb.ChatId,
		userID *commonpb.UserId,
		pointerType messagingpb.Pointer_Type,
		newValue *messagingpb.MessageId,
	) (bool, error)
}