fix(multiplayer): stop the matcher worker crashing on a routine no-match pass

Found building the two-player proposal integration test (next commit):
Worker.Run treated ANY RunOnce error as fatal to the whole loop,
including domain.FormFromQueue's "no compatible candidates" -- which
is not a failure, it's the completely routine and expected outcome of
a queue whose currently-waiting players don't share a verified region
yet. Two real players with no common region formed exactly this
shape, and the entire matcher process exited -- taking matchmaking
down for every OTHER player in the same playlist, not just the
incompatible pair, since cmd/matcher runs one process per playlist.
Worse: on a real supervisor restart, the same still-incompatible
candidates are still queued, so it would crash again immediately --
an actual crash loop, not a one-off.

RunOnce's own per-call contract (return an error for source failure,
bad formation, mixed playlist, an incomplete batch, a lost durable
claim) is deliberately tested and unchanged. The fix is entirely in
Run's loop: only the three genuinely static misconfiguration errors
(nil dependencies, unsupported playlist, invalid size -- true on every
future pass just as much as this one, so retrying can never help) now
stop it, via new exported sentinels (ErrWorkerNotConfigured,
ErrUnsupportedPlaylist, ErrInvalidMatcherSize) and errors.Is. Every
other RunOnce error is a single pass's worth of "no match formed this
time" and Run keeps polling.

Covered by two new tests: Run recovering from a first-pass error and
still forming a proposal once the pool becomes viable (a real
concurrent goroutine driving Run, not just calling RunOnce directly --
Run's own loop had no test coverage at all before this), and Run still
stopping immediately on a genuine configuration error. Both clean
across 3 runs with -race.
This commit is contained in:
Josh Creek
2026-09-01 14:26:19 +01:00
parent 01bb9a9431
commit 3168dd9897
2 changed files with 96 additions and 4 deletions
+22 -4
View File
@@ -4,12 +4,27 @@ package matcher
import (
"context"
"errors"
"fmt"
"time"
"github.com/cosmic-clash/cosmic-clash/server/domain"
)
// These three are the only RunOnce failures Run treats as fatal to the whole
// worker: they're static misconfiguration, true on every future pass just as
// much as this one, so retrying cannot help. Every other RunOnce error --
// a source read hiccup, no common region among the current candidate pool,
// a losing race against another matcher replica, an incomplete batch -- is a
// single pass's worth of "no match formed this time," a routine and
// expected steady state that must not take matching down for every other
// player still waiting behind it.
var (
ErrWorkerNotConfigured = errors.New("matcher worker is not configured")
ErrUnsupportedPlaylist = errors.New("unsupported matcher playlist")
ErrInvalidMatcherSize = errors.New("invalid matcher size")
)
type CandidateSource func(context.Context, time.Time, domain.Playlist, int) ([]domain.Candidate, error)
type ProposalCreator interface {
@@ -42,7 +57,10 @@ func (w Worker) Run(ctx context.Context, interval time.Duration) error {
}
for {
if _, err := w.RunOnce(ctx); err != nil {
return err
if errors.Is(err, ErrWorkerNotConfigured) || errors.Is(err, ErrUnsupportedPlaylist) || errors.Is(err, ErrInvalidMatcherSize) {
return err
}
// Not fatal -- fall through and retry next interval.
}
timer := time.NewTimer(interval)
select {
@@ -59,13 +77,13 @@ func (w Worker) Run(ctx context.Context, interval time.Duration) error {
// a stale cache therefore fails safely and can be retried on the next pass.
func (w Worker) RunOnce(ctx context.Context) (bool, error) {
if w.Source == nil || w.Creator == nil || w.Now == nil || w.NextID == nil || w.Prepare == nil {
return false, fmt.Errorf("matcher worker is not configured")
return false, ErrWorkerNotConfigured
}
if w.Playlist != domain.Casual && w.Playlist != domain.Ranked {
return false, fmt.Errorf("unsupported matcher playlist")
return false, ErrUnsupportedPlaylist
}
if w.Size < 2 || w.Size > 6 {
return false, fmt.Errorf("invalid matcher size")
return false, ErrInvalidMatcherSize
}
now := w.Now()
candidates, err := w.Source(ctx, now, w.Playlist, w.Size)