《MMO 服务器开发》15.1 邮件投递与去重

// file: internal/mail/mail.go
// tier: L1
// verify: go test ./internal/mail/

package mail

import (
	"errors"
	"sync"
	"time"
)

// PlayerID is the whole-server unique role id.
type PlayerID uint64

// MailID identifies one letter. Global-mail templates and personal mails share
// the id space; the high bit of a template id is set so the two never collide.
type MailID uint64

// ItemID is a config-table item id (not an inventory instance id).
type ItemID uint32

// MailKind selects the expiry policy for a mail.
type MailKind uint8

const (
	// KindNormal mails hand their attachments to the bag on expiry.
	KindNormal MailKind = iota
	// KindAuctionReturn is an unsold-auction return: the escrowed item goes
	// back to the seller, and if it is never claimed the expiry sweep settles
	// it into bound currency instead of letting it rot in a dead mail.
	KindAuctionReturn
)

var (
	// ErrDuplicate is returned when the same Mail.ID is delivered twice inside
	// the dedup window.
	ErrDuplicate = errors.New("mail: duplicate delivery")
	// ErrMailboxFull is returned when a mailbox is full and holds no evictable
	// (read and claimed) mail.
	ErrMailboxFull = errors.New("mail: mailbox full")
	// ErrNoSuchMail is returned when a mail id is not present in the mailbox.
	ErrNoSuchMail = errors.New("mail: no such mail")
)

// Attachment is one stack of items carried by a mail.
type Attachment struct {
	ItemID ItemID
	Count  uint32
}

// Mail is a single letter that lives in exactly one player's mailbox.
type Mail struct {
	ID          MailID
	Kind        MailKind
	Sender      string
	Subject     string
	Body        string
	Attachments []Attachment
	CreatedAt   time.Time
	ExpireAt    time.Time
	Read        bool
	Claimed     bool
}

// dedup remembers recently delivered ids so that a re-delivery after the mail
// has been deleted (claimed and removed) is still rejected. It is a plain set
// with lazy pruning: mail volume per player is low, so the O(n) sweep on
// overflow is amortised and beats a per-call scan.
type dedup struct {
	ttl time.Duration
	ids map[MailID]time.Time
}

func newDedup(ttl time.Duration) *dedup {
	return &dedup{ttl: ttl, ids: make(map[MailID]time.Time)}
}

func (d *dedup) seen(id MailID, now time.Time) bool {
	t, ok := d.ids[id]
	return ok && now.Sub(t) < d.ttl
}

func (d *dedup) record(id MailID, now time.Time) {
	d.ids[id] = now
	if len(d.ids) > 4096 {
		d.prune(now)
	}
}

func (d *dedup) prune(now time.Time) {
	for id, t := range d.ids {
		if now.Sub(t) >= d.ttl {
			delete(d.ids, id)
		}
	}
}

// Mailbox is one player's mail store. All methods are safe for concurrent use.
type Mailbox struct {
	mu       sync.Mutex
	owner    PlayerID
	capacity int
	mails    map[MailID]*Mail
	order    []MailID // oldest first
	dedup    *dedup
	claimed  map[MailID][]bool
}

// NewMailbox builds an empty mailbox. capacity is the hard upper bound on live
// mails; dedupTTL is how long a deleted id stays "seen".
func NewMailbox(owner PlayerID, capacity int, dedupTTL time.Duration) *Mailbox {
	if capacity < 1 {
		capacity = 1
	}
	return &Mailbox{
		owner:    owner,
		capacity: capacity,
		mails:    make(map[MailID]*Mail),
		dedup:    newDedup(dedupTTL),
	}
}

// Deliver inserts m and is idempotent: the second delivery of the same id
// inside the dedup window is a no-op that returns ErrDuplicate. When the
// mailbox is full the oldest read-and-claimed mail is evicted; if none is
// evictable the delivery is refused with ErrMailboxFull.
func (mb *Mailbox) Deliver(m *Mail, now time.Time) error {
	mb.mu.Lock()
	defer mb.mu.Unlock()
	if _, ok := mb.mails[m.ID]; ok {
		return ErrDuplicate
	}
	if mb.dedup.seen(m.ID, now) {
		return ErrDuplicate
	}
	if len(mb.mails) >= mb.capacity {
		if !mb.evictOne() {
			return ErrMailboxFull
		}
	}
	mb.dedup.record(m.ID, now)
	cp := *m
	cp.Attachments = append([]Attachment(nil), m.Attachments...)
	mb.mails[m.ID] = &cp
	mb.order = append(mb.order, m.ID)
	return nil
}

func (mb *Mailbox) evictOne() bool {
	for i, id := range mb.order {
		m := mb.mails[id]
		if m.Read && m.Claimed {
			delete(mb.mails, id)
			mb.order = append(mb.order[:i], mb.order[i+1:]...)
			return true
		}
	}
	return false
}

// remove deletes a mail; it is used after a mail is fully claimed and the player
// discards it. The id stays in the dedup set so a late re-delivery is rejected.
func (mb *Mailbox) remove(id MailID) {
	delete(mb.mails, id)
	for i, x := range mb.order {
		if x == id {
			mb.order = append(mb.order[:i], mb.order[i+1:]...)
			break
		}
	}
}

// snippet: internal/mail/mail_test.go（节选）

func TestMailboxEvictsReadClaimed(t *testing.T) {
	mb := NewMailbox(7, 2, time.Hour)
	_ = mb.Deliver(newMail(1, 0), base)
	_ = mb.Deliver(newMail(2, 0), base)
	// 最旧的邮件未读未领，没有可淘汰项。
	if err := mb.Deliver(newMail(3, 0), base); !errors.Is(err, ErrMailboxFull) {
		t.Fatalf("deliver into full mailbox = %v, want ErrMailboxFull", err)
	}
	mb.MarkRead(1)
	if _, err := mb.ClaimAll(1, base); err != nil {
		t.Fatal(err)
	}
	// 现在可淘汰了：同一条 id 3 必须还能投进去，而不是被判重复。
	if err := mb.Deliver(newMail(3, 0), base); err != nil {
		t.Fatalf("deliver after evict = %v", err)
	}
}

// snippet: internal/mail/handler.go（命令接线示意，随第 18 章落地）

// onMailList 处理 CmdMailListReq 0x0A01：先补投该玩家尚未见过的全服模板，
// 再返回整个收件箱。Deliver 自带去重，重复登录不会重复入箱。
func (s *MailService) onMailList(p PlayerID, now time.Time) []Mail {
	mb := s.mailboxOf(p)
	for _, g := range s.pendingGlobals(p, now) {
		_ = mb.Deliver(g, now) // 全服模板展开后的个人邮件
	}
	return mb.List()
}

// onMailClaim 处理 CmdMailClaimReq 0x0A02：邮件 id + 附件下标。
func (s *MailService) onMailClaim(p PlayerID, id MailID, idx int, now time.Time) (Grant, error) {
	return s.mailboxOf(p).Claim(id, idx, now)
}