《MMO 服务器开发》7.3 网关的职责边界

// file: internal/session/gateway.go
// tier: L1
// verify: go test ./internal/session/ -run TestGateway

package session

import (
	"errors"
	"sync"
)

var (
	ErrUnauthorized = errors.New("session: unauthorized")
	ErrRateLimited  = errors.New("session: rate limited")
	ErrNoRoute      = errors.New("session: no route")
)

// Gateway is the network edge. Its job is exactly four things: admit,
// authenticate, rate-limit, and route. It owns no gameplay state, so any
// command whose handling depends on the payload is a boundary violation.
type Gateway struct {
	table *Table
	// Auth decides admission before any Conn exists.
	Auth func(account, token string) bool
	// RatePerWindow is the per-account command budget; 0 disables limiting.
	RatePerWindow int
	// Route maps a command number to a backend name. It receives only cmd --
	// never the payload -- which makes the boundary mechanical.
	Route func(cmd uint16) string

	mu     sync.Mutex
	budget map[string]int
	routed map[string]int
}

// NewGateway wires a gateway onto a session table.
func NewGateway(table *Table, auth func(account, token string) bool, route func(cmd uint16) string) *Gateway {
	return &Gateway{
		table:  table,
		Auth:   auth,
		Route:  route,
		budget: make(map[string]int),
		routed: make(map[string]int),
	}
}

// Admit authenticates before a Conn is ever created. A rejected login never
// reaches the table and never reaches a gameplay backend.
func (g *Gateway) Admit(account, token string) (*Conn, error) {
	if g.Auth == nil || !g.Auth(account, token) {
		return nil, ErrUnauthorized
	}
	c := NewConn(nil)
	g.table.Bind(account, c)
	return c, nil
}

// OnCommand is the only path a gameplay command takes through the gateway. It
// rate-limits, then routes by cmd. It deliberately takes no payload: if the
// gateway cannot read the payload, it cannot accidentally implement gameplay.
func (g *Gateway) OnCommand(account string, cmd uint16) (string, error) {
	if !g.allow(account) {
		return "", ErrRateLimited
	}
	backend := ""
	if g.Route != nil {
		backend = g.Route(cmd)
	}
	if backend == "" {
		return "", ErrNoRoute
	}
	g.mu.Lock()
	g.routed[backend]++
	g.mu.Unlock()
	return backend, nil
}

func (g *Gateway) allow(account string) bool {
	g.mu.Lock()
	defer g.mu.Unlock()
	if g.RatePerWindow > 0 && g.budget[account] >= g.RatePerWindow {
		return false
	}
	g.budget[account]++
	return true
}

// Routed reports how many commands have been routed to backend.
func (g *Gateway) Routed(backend string) int {
	g.mu.Lock()
	defer g.mu.Unlock()
	return g.routed[backend]
}

// snippet: internal/session/limiter.go（节选：令牌桶 Allow）

type Limiter struct {
	rate  float64 // 每秒补充的令牌数
	burst float64 // 桶容量 = 允许的突发上限
	now   func() time.Time

	mu      sync.Mutex
	buckets map[string]*bucket
}

// Allow reports whether key may spend one token right now. It is the whole
// gateway rate limit: no payload, no per-command meaning, just a counter.
func (l *Limiter) Allow(key string) bool {
	l.mu.Lock()
	defer l.mu.Unlock()
	now := l.now()
	b, ok := l.buckets[key]
	if !ok {
		b = &bucket{tokens: l.burst, last: now}
		l.buckets[key] = b
	}
	b.tokens += now.Sub(b.last).Seconds() * l.rate
	if b.tokens > l.burst {
		b.tokens = l.burst
	}
	b.last = now
	if b.tokens < 1 {
		return false
	}
	b.tokens--
	return true
}

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

// routeByModule 只按命令号的模块字节路由，签名里没有 payload。
func routeByModule(cmd uint16) string {
	switch cmd >> 8 {
	case 0x01:
		return "world"
	case 0x02:
		return "scene"
	case 0x03:
		return "chat"
	default:
		return ""
	}
}

// TestGatewayRoutesWithoutPayload proves the boundary mechanically: the router
// signature has no payload argument, so two different payloads with the same
// cmd necessarily route identically.
func TestGatewayRoutesWithoutPayload(t *testing.T) {
	tab := NewTable()
	g := NewGateway(tab, func(_, _ string) bool { return true }, routeByModule)

	b1, err := g.OnCommand("alice", 0x0201) // CmdMoveReq
	if err != nil {
		t.Fatal(err)
	}
	b2, err := g.OnCommand("alice", 0x0302) // CmdChatRecv
	if err != nil {
		t.Fatal(err)
	}
	if b1 != "scene" || b2 != "chat" {
		t.Fatalf("routes = %q, %q; want scene, chat", b1, b2)
	}
	if _, err := g.OnCommand("alice", 0x00FF); err != ErrNoRoute {
		t.Fatalf("unroutable cmd err = %v, want ErrNoRoute", err)
	}
}