《MMO 服务器开发》8.1 路由表与请求-响应-推送

// snippet: internal/router/frame.go（节选）

// 固定头 11 字节：length(4)|cmd(2)|seq(4)|flags(1)
const (
	HeaderSize = 11
	MaxPayload = 1 << 20
)

// Cmd 是 16 位命令号：高字节是模块，低字节是模块内的命令。
type Cmd uint16

// 命令号沿用第 3 章的 internal/proto。
const (
	CmdHeartbeatReq  Cmd = 0x0001
	CmdErrorNotify   Cmd = 0x0003
	CmdLoginReq      Cmd = 0x0010
	CmdEnterWorldReq Cmd = 0x0101
	CmdAttrSync      Cmd = 0x0103
	CmdMoveReq       Cmd = 0x0201
	CmdMoveResp      Cmd = 0x0202
	CmdAoiAdd        Cmd = 0x0203
	CmdChatSend      Cmd = 0x0301
	CmdChatRecv      Cmd = 0x0302
)

// Frame 是一条解码后的帧。Payload 别名解码缓冲区，跨 goroutine 前要复制。
type Frame struct {
	Cmd     Cmd
	Seq     uint32
	Flags   uint8
	Payload []byte
}

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

package router

import (
	"fmt"
	"sync"
)

// Kind classifies a message by its direction and whether a reply is expected.
type Kind uint8

const (
	// KindRequest is client -> server. The client expects exactly one response.
	KindRequest Kind = iota
	// KindPush is server -> client only. The client never replies to it.
	KindPush
	// KindNotify travels in either direction and never expects a response.
	KindNotify
)

// Handler runs one decoded frame. A handler never touches the socket directly:
// it returns an error and the router turns it into a CmdErrorNotify frame, so
// every handler stays trivially testable against a fake connection.
type Handler func(*Context) error

// Conn is the minimal transport the router needs. A real *session.Session from
// chapter 7 satisfies it; tests use an in-memory fake that records frames.
type Conn interface {
	ID() uint64
	Send(cmd Cmd, seq uint32, flags uint8, payload []byte) error
}

// Context is the per-dispatch scratch space handed to a Handler. It carries the
// originating connection, the frame being handled, and the reply command id the
// table knows for this request.
type Context struct {
	Conn     Conn
	Frame    Frame
	ReplyCmd Cmd
}

// Reply sends the response frame back to the originating connection, reusing
// the request's seq so the client can correlate the two. seq correlation is the
// subject of 8.2.
func (c *Context) Reply(payload []byte) error {
	return c.Conn.Send(c.ReplyCmd, c.Frame.Seq, 0, payload)
}

// Push sends a server-initiated frame on the same connection.
func (c *Context) Push(cmd Cmd, payload []byte) error {
	return c.Conn.Send(cmd, 0, 0, payload)
}

// Router maps command ids to handlers and dispatches decoded frames. The table
// is fixed after startup; a sync.RWMutex lets dispatch run fully parallel while
// registration stays safe.
type Router struct {
	mu       sync.RWMutex
	handlers map[Cmd]entry
}

type entry struct {
	kind    Kind
	reply   Cmd
	handler Handler
}

// New returns an empty Router.
func New() *Router { return &Router{handlers: make(map[Cmd]entry)} }

// HandleRequest registers a client request whose response command is reply.
func (r *Router) HandleRequest(cmd, reply Cmd, h Handler) {
	r.mu.Lock()
	defer r.mu.Unlock()
	r.handlers[cmd] = entry{kind: KindRequest, reply: reply, handler: h}
}

// HandleNotify registers a fire-and-forget command (either direction).
func (r *Router) HandleNotify(cmd Cmd, h Handler) {
	r.mu.Lock()
	defer r.mu.Unlock()
	r.handlers[cmd] = entry{kind: KindNotify, handler: h}
}

// HandlePush registers a server-to-client push command. Keeping pushes in the
// same table means a single place can enumerate everything the server may send.
func (r *Router) HandlePush(cmd Cmd, h Handler) {
	r.mu.Lock()
	defer r.mu.Unlock()
	r.handlers[cmd] = entry{kind: KindPush, handler: h}
}

// Dispatch routes one frame to its handler. An unknown command id, or a handler
// that returns an error, produces a CmdErrorNotify frame instead of a panic, so
// a hostile or stale client cannot take down the read loop.
func (r *Router) Dispatch(c Conn, f Frame) error {
	r.mu.RLock()
	e, ok := r.handlers[f.Cmd]
	r.mu.RUnlock()
	if !ok {
		msg := fmt.Sprintf("unknown cmd 0x%04x", uint16(f.Cmd))
		return c.Send(CmdErrorNotify, f.Seq, 0, []byte(msg))
	}
	ctx := &Context{Conn: c, Frame: f, ReplyCmd: e.reply}
	if err := e.handler(ctx); err != nil {
		return c.Send(CmdErrorNotify, f.Seq, 0, []byte(err.Error()))
	}
	return nil
}

// KindOf reports how a command was registered, for tests and tooling.
func (r *Router) KindOf(cmd Cmd) (Kind, bool) {
	r.mu.RLock()
	defer r.mu.RUnlock()
	e, ok := r.handlers[cmd]
	return e.kind, ok
}

// Len reports how many commands are registered.
func (r *Router) Len() int {
	r.mu.RLock()
	defer r.mu.RUnlock()
	return len(r.handlers)
}

// snippet: internal/router/router_test.go（节选）

type fakeConn struct {
	id   uint64
	mu   sync.Mutex
	sent []Frame
}

func (c *fakeConn) ID() uint64 { return c.id }

func (c *fakeConn) Send(cmd Cmd, seq uint32, flags uint8, payload []byte) error {
	c.mu.Lock()
	defer c.mu.Unlock()
	c.sent = append(c.sent, Frame{Cmd: cmd, Seq: seq, Flags: flags, Payload: append([]byte(nil), payload...)})
	return nil
}

func TestDispatchRequestReply(t *testing.T) {
	r := New()
	r.HandleRequest(CmdMoveReq, CmdMoveResp, func(ctx *Context) error {
		return ctx.Reply([]byte("moved"))
	})
	c := &fakeConn{id: 1}
	if err := r.Dispatch(c, Frame{Cmd: CmdMoveReq, Seq: 42}); err != nil {
		t.Fatalf("dispatch: %v", err)
	}
	got, ok := c.last()
	if !ok || got.Cmd != CmdMoveResp {
		t.Fatalf("reply = %+v, want CmdMoveResp", got)
	}
	if got.Seq != 42 {
		t.Fatalf("reply seq = %d, want the request seq 42", got.Seq)
	}
}

func TestUnknownCommandYieldsErrorNotify(t *testing.T) {
	r := New()
	c := &fakeConn{id: 7}
	_ = r.Dispatch(c, Frame{Cmd: Cmd(0x7fff), Seq: 5})
	got, _ := c.last()
	if got.Cmd != CmdErrorNotify || got.Seq != 5 {
		t.Fatalf("want an error notify with seq 5, got %+v", got)
	}
}

$ go vet ./... && go test ./internal/router/
ok  	aegis/internal/router	0.704s