《MMO 服务器开发》14.1 服务器时间线与时钟同步

   客户端                    服务端
     t1 ──── 请求 ────────────→ t2    （服务端收到的时刻）
     t4 ←─── 响应 ───────────── t3    （服务端发出的时刻）

   offset = ((t2 − t1) + (t3 − t4)) / 2      ← 服务端时钟 − 客户端时钟
   rtt    = (t4 − t1) − (t3 − t2)            ← 扣掉服务端处理时间后的往返

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

package clock

import (
	"errors"
	"sync"
	"time"
)

// Source reads a monotonic counter. Production passes a closure over
// time.Since(boot); tests pass a virtual counter so every number below is
// reproducible.
type Source func() time.Duration

// ErrNoSamples is returned by Estimator.Best before any sample is recorded.
var ErrNoSamples = errors.New("clock: no offset samples")

// Offset is one NTP-style four-timestamp measurement. t1,t4 are stamped on the
// client clock, t2,t3 on the server clock. No shared epoch is required, which is
// exactly why the method survives clocks that were never synchronised.
type Offset struct {
	RTT    time.Duration
	Offset time.Duration // server_clock - client_clock at the round-trip midpoint
}

// Measure derives the offset and round-trip time from the four timestamps.
func Measure(t1, t2, t3, t4 time.Duration) Offset {
	rtt := (t4 - t1) - (t3 - t2)
	if rtt < 0 {
		rtt = 0
	}
	return Offset{RTT: rtt, Offset: ((t2 - t1) + (t3 - t4)) / 2}
}

// Estimator keeps a sliding window of samples and returns the one with the
// lowest RTT. Queueing only ever adds delay, so the fastest sample is the least
// distorted; taking the minimum is a cheap stand-in for a full NTP filter.
type Estimator struct {
	window  int
	samples []Offset
}

// NewEstimator builds an estimator holding at most window samples.
func NewEstimator(window int) *Estimator {
	if window < 1 {
		window = 1
	}
	return &Estimator{window: window}
}

// Add records a sample, dropping the oldest once the window is full.
func (e *Estimator) Add(o Offset) {
	e.samples = append(e.samples, o)
	if len(e.samples) > e.window {
		e.samples = e.samples[len(e.samples)-e.window:]
	}
}

// Best returns the lowest-RTT sample, or ErrNoSamples when the window is empty.
func (e *Estimator) Best() (Offset, error) {
	if len(e.samples) == 0 {
		return Offset{}, ErrNoSamples
	}
	best := e.samples[0]
	for _, s := range e.samples[1:] {
		if s.RTT < best.RTT {
			best = s
		}
	}
	return best, nil
}

// JumpThreshold: a source move larger than this between two reads is treated as
// a host clock correction (NTP step), not as real elapsed time.
const JumpThreshold = 2 * time.Second

// Timeline is the server's authoritative time line. Gameplay never reads a
// wall-clock instant: it reads Elapsed, which only ever moves forward. A
// backward NTP step is absorbed instead of propagated, so the world cannot
// rewind under a running simulation.
type Timeline struct {
	mu       sync.Mutex
	source   Source
	last     time.Duration
	elapsed  time.Duration
	backward int
	forward  int
}

// NewTimeline starts a timeline at the source's current reading.
func NewTimeline(source Source) *Timeline {
	return &Timeline{source: source, last: source()}
}

// Elapsed advances by the source delta and returns total monotonic time since
// construction. Backward steps are clamped to zero (the timeline never rewinds);
// forward steps beyond JumpThreshold are counted as corrections.
func (t *Timeline) Elapsed() time.Duration {
	t.mu.Lock()
	defer t.mu.Unlock()
	now := t.source()
	delta := now - t.last
	switch {
	case delta < 0:
		t.backward++
		delta = 0
	case delta > JumpThreshold:
		t.forward++
	}
	t.last = now
	t.elapsed += delta
	return t.elapsed
}

// BackwardJumps reports how many times the source stepped backwards.
func (t *Timeline) BackwardJumps() int {
	t.mu.Lock()
	defer t.mu.Unlock()
	return t.backward
}

// ForwardJumps reports how many forward corrections exceeded JumpThreshold.
func (t *Timeline) ForwardJumps() int {
	t.mu.Lock()
	defer t.mu.Unlock()
	return t.forward
}

// snippet: internal/clock/clock_test.go（节选）

func TestTimelineAbsorbsBackwardStep(t *testing.T) {
	var now = 100 * time.Millisecond
	tl := NewTimeline(func() time.Duration { return now })

	now += 50 * time.Millisecond
	if got := tl.Elapsed(); got != 50*time.Millisecond {
		t.Fatalf("elapsed = %v, want 50ms", got)
	}
	// Host clock is corrected 30ms backwards: the timeline must not rewind.
	now -= 30 * time.Millisecond
	if got := tl.Elapsed(); got != 50*time.Millisecond {
		t.Fatalf("elapsed after backward step = %v, want 50ms (held)", got)
	}
	if tl.BackwardJumps() != 1 {
		t.Fatalf("backward jumps = %d, want 1", tl.BackwardJumps())
	}
	now += 20 * time.Millisecond
	if got := tl.Elapsed(); got != 70*time.Millisecond {
		t.Fatalf("elapsed = %v, want 70ms", got)
	}
}