《MMO 服务器开发》7.2 顶号、踢人与连接迁移

固定头 11 字节：length(4, BE) | cmd(2, BE) | seq(4, BE) | flags(1)
踢号通知：cmd = CmdErrorNotify = 0x0003
payload = reason_code(2, BE) + msg_len(2, BE) + utf8_msg
length = 7 + len(payload)，帧总长 = 11 + len(payload)，MaxPayload = 1 << 20

// file: internal/session/kick.go
// tier: L1
// verify: go test ./internal/session/ -run TestKick

package session

import "sync"

// Registrar enforces the "one live session per account" invariant on top of a
// Table. Login evicts and closes a previous session; Migrate hands it off
// without closing it.
type Registrar struct {
	table *Table

	mu     sync.Mutex
	kicked map[string]int
}

// NewRegistrar returns a registrar bound to table.
func NewRegistrar(table *Table) *Registrar {
	return &Registrar{table: table, kicked: make(map[string]int)}
}

// Login binds c to account. If another live connection already holds the
// account it is evicted from the table first, then closed, so the old
// connection's disconnect handler (Table.Remove) can never delete the new
// binding: by the time it runs, its connID is already gone.
func (r *Registrar) Login(account string, c *Conn) {
	old := r.table.Bind(account, c)
	if old == nil {
		return
	}
	r.mu.Lock()
	r.kicked[account]++
	r.mu.Unlock()
	_ = old.Close()
}

// Migrate rebinds an existing account to a new connection (for example after
// the player is moved to another gateway). Unlike Login it does NOT close the
// old conn: the caller drains it gracefully so in-flight frames are not lost.
func (r *Registrar) Migrate(account string, c *Conn) (old *Conn) {
	return r.table.Bind(account, c)
}

// Kick force-closes whatever session currently holds account, without a new
// login taking its place. Admin tools and risk control use it. It removes the
// conn from the table before closing, for the same reason Login does. It
// returns ErrUnknownConn when the account is already offline.
func (r *Registrar) Kick(account string) error {
	c, ok := r.table.Lookup(account)
	if !ok {
		return ErrUnknownConn
	}
	r.mu.Lock()
	r.kicked[account]++
	r.mu.Unlock()
	r.table.Remove(c.ID)
	return c.Close()
}

// Kicked returns how many times account has been force-evicted by a later
// login. A non-zero value is a healthy signal, not an error.
func (r *Registrar) Kicked(account string) int {
	r.mu.Lock()
	defer r.mu.Unlock()
	return r.kicked[account]
}

// snippet: internal/session/kick_test.go（节选）

func TestKickSecondLoginEvictsFirst(t *testing.T) {
	tab := NewTable()
	reg := NewRegistrar(tab)

	first := NewConn(nil)
	first.onClose = func(c *Conn) { tab.Remove(c.ID) } // 旧连接的清理
	reg.Login("alice", first)

	second := NewConn(nil)
	second.onClose = func(c *Conn) { tab.Remove(c.ID) }
	reg.Login("alice", second) // 顶号：先摘 first，再关 first

	if !first.Closed() {
		t.Fatal("first session was not closed on takeover")
	}
	if second.Closed() {
		t.Fatal("second session must stay open")
	}
	if got, ok := tab.Lookup("alice"); !ok || got != second {
		t.Fatalf("Lookup(alice) = %v, %v; want the second session", got, ok)
	}
	if n := tab.Len(); n != 1 {
		t.Fatalf("Len = %d, want 1", n)
	}
}

Login(alice, first)          Login(alice, second)         first 的 socket 终于死
     |                              |                              |
  Bind: byAcc[alice]=first      Bind: 摘掉 first               first.Close() 已跑过
                                     byAcc[alice]=second          或回调 Remove(first.ID)
                                     first.Close() -> Remove         -> byConn 里没有 -> 空操作
                                          (表里已无 first)          -> 新会话安然无恙

// snippet: internal/session/kick_test.go（节选）

func TestAdminKickRemovesSession(t *testing.T) {
	tab := NewTable()
	reg := NewRegistrar(tab)

	c := NewConn(nil)
	c.onClose = func(x *Conn) { tab.Remove(x.ID) }
	reg.Login("carol", c)

	if err := reg.Kick("carol"); err != nil {
		t.Fatalf("Kick(carol) err = %v", err)
	}
	if !c.Closed() {
		t.Fatal("kicked session is still open")
	}
	if _, ok := tab.Lookup("carol"); ok {
		t.Fatal("kicked session is still indexed")
	}
	if err := reg.Kick("carol"); err != ErrUnknownConn {
		t.Fatalf("Kick(offline) = %v, want ErrUnknownConn", err)
	}
}

// snippet: internal/session/kick_test.go（节选）

func TestMigrateKeepsOldOpen(t *testing.T) {
	tab := NewTable()
	reg := NewRegistrar(tab)

	old := NewConn(nil)
	reg.Migrate("bob", old)

	drained := NewConn(nil)
	if ev := reg.Migrate("bob", drained); ev != old {
		t.Fatalf("Migrate returned %v, want the old conn", ev)
	}
	if old.Closed() {
		t.Fatal("Migrate must not close the old conn")
	}
	if n := reg.Kicked("bob"); n != 0 {
		t.Fatalf("Migrate must not count as a kick, got %d", n)
	}
}