poll

type Poll struct {
	ID              *pollpb.PollId
	ChatID          *commonpb.ChatId
	CreatorID       *commonpb.UserId
	Definition      *pollpb.PollDefinition
	CreatedAt       time.Time
	Live            bool
	ClientMessageID *messagingpb.ClientMessageId
	Status          Status
	Results         *pollpb.Results
}

type Server struct {
	pollpb.UnimplementedPollServer
	// contains filtered or unexported fields
}

type ServerOption func(*Server)

type Status uint8

type Store interface {
	// CreatePoll writes a new poll as given, live or not (see Poll.Live), with
	// status open and no results, and a live one enqueued for the tally.
	// ErrPollExists is returned, and nothing is written, when a poll with its
	// ID already exists.
	CreatePoll(ctx context.Context, p *Poll) error

	// GetPoll returns a poll, or ErrPollNotFound.
	GetPoll(ctx context.Context, pollID *pollpb.PollId) (*Poll, error)

	// GetPolls returns each of the given polls that exists, keyed by
	// string(pollID.Value). Polls that do not exist are absent from the map,
	// as are duplicates beyond the first.
	GetPolls(ctx context.Context, pollIDs []*pollpb.PollId) (map[string]*Poll, error)

	// MarkLive makes an unsent poll live (see Poll.Live) as sent by the
	// message with clientMessageID, recording it as Poll.ClientMessageID and
	// enqueuing the poll for the tally, and reports whether it changed
	// anything: a poll already live by that message is a no-op, and one live
	// otherwise, by another send or from creation, is ErrPollAlreadyLive, so of
	// any number of sends racing to make a poll live exactly one does. ErrPollNotFound is returned for a poll that does not
	// exist, or that ended unsent at or before now and so has been discarded.
	MarkLive(ctx context.Context, pollID *pollpb.PollId, clientMessageID *messagingpb.ClientMessageId, now time.Time) (changed bool, err error)

	// SetVote replaces userID's vote in a poll with options, as cast at
	// votedAt, or removes it when options is empty. Nothing is checked against
	// the poll, which need not even exist: the caller has established that the
	// poll is open and the options are a valid selection in it.
	SetVote(ctx context.Context, pollID *pollpb.PollId, userID *commonpb.UserId, options []uint32, votedAt time.Time) error

	// GetVotes returns userID's vote in each of the given polls they have voted
	// in, as its options in ascending order, keyed by string(pollID.Value).
	// Polls they have not voted in are absent.
	GetVotes(ctx context.Context, userID *commonpb.UserId, pollIDs []*pollpb.PollId) (map[string][]uint32, error)

	// GetVotesPage returns up to limit of a poll's votes in ascending order of
	// voter ID, strictly after the voter after (from the first when nil). An
	// empty page means there are no more.
	GetVotesPage(ctx context.Context, pollID *pollpb.PollId, after *commonpb.UserId, limit int) ([]Vote, error)

	// GetDueForTally returns up to limit polls on the tally queue whose due time
	// is at or before asOf, soonest first. The queue is eventually consistent:
	// a poll just claimed or closed may still be listed, which ClaimForTally
	// settles.
	GetDueForTally(ctx context.Context, asOf time.Time, limit int) ([]*TallyTask, error)

	// GetTallyQueueStats reports the tally's backlog as of asOf: how many
	// queued polls are due, counting at most MaxTallyQueueStatsDepth, and the
	// due time of the most overdue. Polls not yet due are never read, so its
	// cost follows the backlog, not the number of open polls. It is eventually
	// consistent, like GetDueForTally.
	GetTallyQueueStats(ctx context.Context, asOf time.Time) (*TallyQueueStats, error)

	// ClaimForTally pushes a queued poll's due time out to until, provided it
	// is still queued and due as of asOf. It reports whether the claim was
	// performed: false means the poll left the queue (it was closed) or is no
	// longer due (another server claimed or delayed it first).
	//
	// A claim is an efficiency guard, not a lock: a tally is idempotent and
	// safe to run concurrently, and claiming only keeps servers from
	// duplicating its reads. A crashed claimant needs no recovery: the claim
	// expires when its until passes and the poll simply becomes due again.
	ClaimForTally(ctx context.Context, pollID *pollpb.PollId, asOf, until time.Time) (bool, error)

	// DelayTally reschedules a queued poll after a failed attempt: its due
	// time moves to nextAttemptAt and its failed-attempt count increments. It
	// is a no-op on a poll that is no longer queued (a concurrent tally closed
	// it, dequeuing it).
	DelayTally(ctx context.Context, pollID *pollpb.PollId, nextAttemptAt time.Time) error

	// Close records a live poll's results, moves it to closed and dequeues it
	// from the tally queue, and reports whether it changed anything: a poll already
	// closed is a no-op that keeps its results. ErrPollNotFound is returned for
	// a poll that does not exist, and ErrPollNotLive for one that never went
	// live. Whether the poll has ended, and its votes are all in, is the
	// caller's (see TallyDelay).
	Close(ctx context.Context, pollID *pollpb.PollId, results *pollpb.Results) (changed bool, err error)
}

type TallyQueueStats struct {
	// DueDepth is how many queued polls are due, at most
	// MaxTallyQueueStatsDepth.
	DueDepth uint64

	// OldestDueAt is the due time of the most overdue poll, or the zero time
	// when none is due.
	OldestDueAt time.Time
}

type TallyTask struct {
	ID *pollpb.PollId

	// Attempts is the number of failed tally attempts recorded so far (via
	// Store.DelayTally). The tally uses it to pace backoff.
	Attempts uint32

	// NextAttemptAt is when the task next becomes due: TallyDelay after the
	// poll ends at first (see TallyDueAt), then whenever a claim or a delay
	// moves it.
	NextAttemptAt time.Time
}

type Vote struct {
	UserID  *commonpb.UserId
	Options []uint32
	VotedAt time.Time
}

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

type WorkerOption func(*Worker)