《MMO 服务器开发》5.1 实例调度器

// file: internal/scheduler/types.go
// tier: L1
// verify: go test ./internal/scheduler/
package scheduler

import "fmt"

// ServerID 是区服号（uint16），沿用全卷共享类型：参与 EntityID 高位与雪花 worker id。
type ServerID uint16

// InstanceID 是地图实例 ID（uint64）。
type InstanceID uint64

// NodeID 是集群节点标识，形如 scene-01、gateway-03。
type NodeID string

// Kind 区分三类被调度的实例。
type Kind uint8

const (
	KindScene  Kind = iota // 场景服：承载一张常驻地图的在线玩家
	KindBattle             // 战斗服：为一场副本 / 战场临时开出
	KindWorld              // 世界服：跨场景的全局逻辑（拍卖行、排行、跨服）
)

// State 是实例生命周期状态：创建 → 就绪 → 分配 → 使用 → 回收 → 销毁。
type State uint8

const (
	StateCreated   State = iota // 进程已起，尚未就绪
	StateReady                  // 已就绪，可被分配
	StateAllocated              // 已分配给某个玩法
	StateInUse                  // 使用中（有玩家在）
	StateRecycling              // 回收中（等待玩家排空）
	StateGone                   // 已销毁
)

var stateNames = [...]string{"created", "ready", "allocated", "in-use", "recycling", "gone"}

func (s State) String() string {
	if int(s) < len(stateNames) {
		return stateNames[s]
	}
	return "unknown"
}

// allowed 是实例生命周期状态机。只允许表里的迁移；任何跳步都返回错误，
// 而不是静默推进——「实例现在能不能接玩家」永远由这张表回答。
var allowed = map[State][]State{
	StateCreated:   {StateReady, StateGone},
	StateReady:     {StateAllocated, StateRecycling},
	StateAllocated: {StateInUse, StateReady, StateRecycling},
	StateInUse:     {StateRecycling},
	StateRecycling: {StateGone},
	StateGone:      {},
}

// Instance 是调度器眼里的一个实例。
type Instance struct {
	ID     InstanceID
	Kind   Kind
	Node   NodeID
	Server ServerID
	State  State
	Addr   string // 实例对外地址，就绪后才有
}

// Advance 把实例推进到目标状态；非法迁移返回错误，状态保持不变。
func (in *Instance) Advance(to State) error {
	for _, ok := range allowed[in.State] {
		if ok == to {
			in.State = to
			return nil
		}
	}
	return fmt.Errorf("instance %d: illegal transition %s -> %s", in.ID, in.State, to)
}

// Assignable 回答「这个实例现在能不能被分配出去」——只有就绪态可以。
func (in *Instance) Assignable() bool { return in.State == StateReady }

// file: internal/scheduler/scheduler.go
// tier: L2
// verify: go test ./internal/scheduler/ -run TestSchedulerSpawnsRealInstance
package scheduler

import (
	"bufio"
	"context"
	"fmt"
	"os/exec"
	"strings"
	"sync"
)

// Launcher 起一个实例进程，返回它的对外地址。真实实现 fork 子进程；
// 测试里可注入假实现，把调度逻辑与进程管理解耦。
type Launcher interface {
	Launch(ctx context.Context, id InstanceID, kind Kind, server ServerID) (addr string, err error)
}

// Scheduler 负责「什么时候开一个实例、开完等它就绪」：分配 ID、调 Launcher
// 起进程、把状态从创建推进到就绪。起不来就推进到销毁，绝不留下半死状态。
type Scheduler struct {
	mu        sync.Mutex
	nextID    InstanceID
	launcher  Launcher
	instances map[InstanceID]*Instance
}

func New(launcher Launcher) *Scheduler {
	return &Scheduler{nextID: 1, launcher: launcher, instances: make(map[InstanceID]*Instance)}
}

// Create 起一个实例并推进到就绪态：创建 → (launch) → 就绪。
func (s *Scheduler) Create(ctx context.Context, kind Kind, server ServerID, node NodeID) (*Instance, error) {
	s.mu.Lock()
	id := s.nextID
	s.nextID++
	in := &Instance{ID: id, Kind: kind, Server: server, Node: node, State: StateCreated}
	s.instances[id] = in
	s.mu.Unlock()

	addr, err := s.launcher.Launch(ctx, id, kind, server)
	if err != nil {
		_ = in.Advance(StateGone)
		return nil, fmt.Errorf("launch instance %d: %w", id, err)
	}
	in.Addr = addr
	if err := in.Advance(StateReady); err != nil {
		return nil, err
	}
	return in, nil
}

// ProcessLauncher 真起一个实例进程：exec 指定二进制，从它的 stdout 读到
// 「READY addr=...」才认为就绪。子进程挂在 ctx 上，ctx 取消（或超时）时
// 被自动杀掉——这是「就绪超时」这一状态的根本保障。
type ProcessLauncher struct {
	Bin  string
	Args []string
}

func (p *ProcessLauncher) Launch(ctx context.Context, id InstanceID, kind Kind, server ServerID) (string, error) {
	args := append(append([]string{}, p.Args...), "-id", fmt.Sprint(id), "-kind", fmt.Sprint(int(kind)), "-server", fmt.Sprint(server))
	cmd := exec.CommandContext(ctx, p.Bin, args...)
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		return "", err
	}
	if err := cmd.Start(); err != nil {
		return "", err
	}
	sc := bufio.NewScanner(stdout)
	for sc.Scan() {
		if line := sc.Text(); strings.HasPrefix(line, "READY addr=") {
			return strings.Fields(strings.TrimPrefix(line, "READY addr="))[0], nil
		}
	}
	_ = cmd.Process.Kill()
	return "", fmt.Errorf("instance %d exited before ready", id)
}

// file: internal/scheduler/spawn_test.go
// tier: L2
// verify: go test ./internal/scheduler/ -run TestSchedulerSpawnsRealInstance
package scheduler

import (
	"context"
	"net"
	"os/exec"
	"path/filepath"
	"testing"
	"time"
)

// buildSceneInstance 把 cmd/sceneinstance 编译到临时目录，返回二进制路径。
// 测试自己编译，保证「跑的就是当前源码」，不依赖预先构建的产物。
func buildSceneInstance(t *testing.T) string {
	t.Helper()
	bin := filepath.Join(t.TempDir(), "sceneinstance")
	cmd := exec.Command("go", "build", "-o", bin, "./cmd/sceneinstance")
	cmd.Dir = "../.." // 从 internal/scheduler 回到 module 根
	if out, err := cmd.CombinedOutput(); err != nil {
		t.Fatalf("build sceneinstance: %v\n%s", err, out)
	}
	return bin
}

// TestSchedulerSpawnsRealInstance 真起一个实例进程：调度器读到 READY 后
// 把它推进到就绪，测试再拨号连它的地址，证明进程确实在监听。
func TestSchedulerSpawnsRealInstance(t *testing.T) {
	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
	defer cancel()

	s := New(&ProcessLauncher{Bin: buildSceneInstance(t)})
	in, err := s.Create(ctx, KindBattle, 7, "battle-01")
	if err != nil {
		t.Fatalf("create: %v", err)
	}
	if in.State != StateReady {
		t.Fatalf("state = %s, want ready", in.State)
	}
	conn, err := net.DialTimeout("tcp", in.Addr, 2*time.Second)
	if err != nil {
		t.Fatalf("dial instance %s: %v", in.Addr, err)
	}
	_ = conn.Close()
}

// TestLaunchFailureGoesToGone 用一个必定失败的 Launcher，断言实例被推进
// 到销毁而不是卡在创建态。
func TestLaunchFailureGoesToGone(t *testing.T) {
	s := New(failingLauncher{})
	in, err := s.Create(context.Background(), KindScene, 1, "scene-99")
	if err == nil {
		t.Fatal("expected launch error")
	}
	if in != nil {
		t.Fatalf("expected nil instance, got %+v", in)
	}
}

type failingLauncher struct{}

func (failingLauncher) Launch(context.Context, InstanceID, Kind, ServerID) (string, error) {
	return "", exec.ErrNotFound
}