[Proposal] Matchmaker: investigate single-document reverse-query evaluation
Description
This is a feature/performance investigation, not a report of an observed production failure.
When matchmaker.rev_precision is enabled, validateMatch validates the reverse direction of a candidate pair by executing a second Bluge search on the current matchmaker index:
candidateQuery AND _id:targetTicketThe _id predicate limits the result cardinality to at most one document, but an uncached directional pair still constructs and executes an index-backed query. The reverse result is then cached in revCache.
Could the built-in matchmaker instead use a single-document evaluator for this specific reverse-validation operation, while preserving current matchmaker query behavior and ticket-lifecycle semantics?
This is motivated by source-level investigation, not by a claim of a measured regression. Any change should be accepted only if it demonstrates behavioral equivalence and a measurable improvement for cold reverse-cache misses.
Relevant prior art:
- #714 explicitly identified potential n-squared reverse-query work and considered an ID-constrained second Bluge query versus a single-document evaluator.
- #719 introduced the current minimal mutual-match validation path.
blugelabs/souris a separate, Bluge-native single-document evaluator designed to answer whether abluge.Documentmatches abluge.Query. It is not currently a drop-in dependency: it is non-thread-safe and targets Bluge v0.1.8, while Nakama vendors v0.2.2.
Before preparing an implementation PR, I would like maintainer direction on:
- Whether this optimization is desirable for the built-in matchmaker.
- Whether an evaluator should live in Nakama, be an updated
souradapter, or be contributed upstream to Bluge. - Which compatibility and benchmark scenarios would be required for review.
Steps to Reproduce
Nothing to reproduce. The current implementation behavior:
- Enable
matchmaker.rev_precision: true. - Add tickets A and B such that A's query matches B's properties.
- Run a matchmaking pass with no cached
B -> Aresult. - Inspect
server/matchmaker_process.goandserver/matchmaker.go:processDefaultcallsvalidateMatchwith B's parsed query and A's ticket ID, andvalidateMatchexecutesReader.Searchfor_id:A AND B.query.
Expected Result
N/A
Actual Result
N/A
Context
- Unity
- Unreal
- Other: Nakama server matchmaker implementation and its in-memory Bluge index.
Your Environment
- Nakama: source checkout at
b85a08cc1975685aa8f7b8b76e52922a253b55e6 - Database: N/A for the source-level/unit-test investigation
- Environment name and version: local source checkout, Go 1.26.5
- Operating System and version: macOS (Darwin/arm64)
Source: heroiclabs/nakama