《游戏服务端架构·品类、状态与拓扑》5.1 长连接、短连接、WebSocket 与 QUIC 的取舍

// file: internal/conn/profile.go
// tier: L1
// verify: go test ./internal/conn/
package conn

import (
	"errors"
	"sort"
	"time"
)

// Transport is a wire shape a product ships, not a library choice.
type Transport string

const (
	ShortHTTP    Transport = "http-short"
	LongPoll     Transport = "http-longpoll"
	WebSocket    Transport = "websocket"
	QUICStream   Transport = "quic-stream"
	QUICDatagram Transport = "quic-datagram"
)

// Profile records decision-relevant properties. LatencyFloorMS is the lowest
// one-way latency the shape can sustain, not a benchmark result.
type Profile struct {
	Transport      Transport
	LatencyFloorMS int
	ServerPush     bool
	PersistentPush bool
	CDNSafe        bool
	Migration      bool
	ResumeFriendly bool
	HandshakeRTTs  int
	OpsCost        int
	RunsOverUDP    bool
	LossTolerant   bool
}

var catalog = []Profile{
	{ShortHTTP, 250, false, false, true, false, true, 2, 0, false, false},
	{LongPoll, 120, true, false, true, false, true, 2, 1, false, false},
	{WebSocket, 40, true, true, true, false, true, 2, 1, false, false},
	{QUICStream, 25, true, true, false, true, true, 1, 2, true, false},
	{QUICDatagram, 20, false, false, false, true, false, 1, 3, true, true},
}

// Requirements are constraints from genre, network and team shape.
type Requirements struct {
	MaxOneWayMS  int
	ServerPush   bool
	WeakMobile   bool
	MustPassCDN  bool
	LossTolerant bool
	TeamSize     int
}

// ErrNoFit means every catalog entry violates a hard requirement.
var ErrNoFit = errors.New("conn: no transport fits the requirements")

// Decision carries the winner and the eligible ranking for an ADR appendix.
type Decision struct {
	Profile Profile
	Score   int
	Ranked  []Profile
}

func eligible(p Profile, req Requirements) bool {
	if req.MaxOneWayMS < p.LatencyFloorMS {
		return false
	}
	if req.ServerPush && !p.ServerPush {
		return false
	}
	if req.MustPassCDN && !p.CDNSafe {
		return false
	}
	if req.LossTolerant && !p.LossTolerant {
		return false
	}
	// A two-person team should not operate its own UDP fleet for a product
	// that already tolerates 200ms.
	if req.TeamSize <= 2 && req.MaxOneWayMS >= 200 && p.RunsOverUDP {
		return false
	}
	return true
}

func score(p Profile, req Requirements) int {
	s := 100 - p.HandshakeRTTs*3
	if req.WeakMobile {
		if p.Migration {
			s += 12
		}
		if p.ResumeFriendly {
			s += 4
		}
	}
	if req.ServerPush && p.PersistentPush {
		s += 8
	}
	if req.TeamSize <= 3 {
		s -= p.OpsCost * 6
	}
	if p.RunsOverUDP {
		s -= p.OpsCost * 2
	}
	if req.LossTolerant && p.LossTolerant {
		s += 10
	}
	return s
}

// Recommend scores every eligible profile and breaks ties by lower latency
// floor, then by transport name, so the result is reproducible in an ADR.
func Recommend(req Requirements) (Decision, error) {
	type scored struct {
		p Profile
		s int
	}
	var list []scored
	for _, p := range catalog {
		if eligible(p, req) {
			list = append(list, scored{p, score(p, req)})
		}
	}
	if len(list) == 0 {
		return Decision{}, ErrNoFit
	}
	sort.Slice(list, func(i, j int) bool {
		if list[i].s != list[j].s {
			return list[i].s > list[j].s
		}
		if list[i].p.LatencyFloorMS != list[j].p.LatencyFloorMS {
			return list[i].p.LatencyFloorMS < list[j].p.LatencyFloorMS
		}
		return list[i].p.Transport < list[j].p.Transport
	})
	out := Decision{Profile: list[0].p, Score: list[0].s}
	for _, item := range list {
		out.Ranked = append(out.Ranked, item.p)
	}
	return out, nil
}

// HandshakePlan describes what must happen before the first game byte.
type HandshakePlan struct {
	TLS      bool
	Resume   bool
	AuthRTTs int
}

// Handshake is the connection-setup cost in round trips and milliseconds.
type Handshake struct {
	RoundTrips int
	Millis     int
	Resumed    bool
}

// EstimateHandshake uses TLS 1.3 (one round trip after the TCP handshake).
// A resumed session is modelled as one round trip regardless of authRTTs.
func EstimateHandshake(rttMS int, plan HandshakePlan) Handshake {
	if rttMS <= 0 {
		rttMS = 1
	}
	rt := 1 + plan.AuthRTTs
	if plan.TLS && !plan.Resume {
		rt++
	}
	if plan.Resume {
		rt = 1
	}
	return Handshake{RoundTrips: rt, Millis: rt * rttMS, Resumed: plan.Resume}
}

// ReconnectPolicy is exponential backoff plus a resumable-session window.
type ReconnectPolicy struct {
	Base         time.Duration
	Cap          time.Duration
	MaxAttempts  int
	ResumeWindow time.Duration
	JitterRatio  float64
}

// Delay returns the wait before attempt (1-based). unit in [0,1] is supplied
// by the caller; unit=0 is the jitter-free control used by tests.
func (p ReconnectPolicy) Delay(attempt int, unit float64) (time.Duration, bool) {
	if attempt < 1 || attempt > p.MaxAttempts || p.Base <= 0 {
		return 0, false
	}
	d := p.Base
	for i := 1; i < attempt && d < p.Cap; i++ {
		d *= 2
	}
	if p.Cap > 0 && d > p.Cap {
		d = p.Cap
	}
	if unit < 0 {
		unit = 0
	}
	if unit >= 1 {
		unit = 1
	}
	ratio := p.JitterRatio
	if ratio < 0 {
		ratio = 0
	}
	if ratio > 1 {
		ratio = 1
	}
	return time.Duration(float64(d) * (1 - ratio*unit)), true
}

// CanResume reports whether a gap still falls inside the resume window.
func (p ReconnectPolicy) CanResume(gap time.Duration) bool {
	return gap >= 0 && gap <= p.ResumeWindow
}

$ cd .local/checks/gsarch-lab
$ gofmt -l internal/conn
$ go vet ./internal/conn/
$ go test -count=1 ./internal/conn/ -v
...
PASS
ok  	gsarchlab/internal/conn	0.308s