#2546·nakama

[Proposal] Matchmaker: investigate single-document reverse-query evaluation

Author: yaosongdingCreated Aug 28, 2026Updated Aug 28, 2026

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:targetTicket

The _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/sour is a separate, Bluge-native single-document evaluator designed to answer whether a bluge.Document matches a bluge.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:

  1. Whether this optimization is desirable for the built-in matchmaker.
  2. Whether an evaluator should live in Nakama, be an updated sour adapter, or be contributed upstream to Bluge.
  3. Which compatibility and benchmark scenarios would be required for review.

Steps to Reproduce

Nothing to reproduce. The current implementation behavior:

  1. Enable matchmaker.rev_precision: true.
  2. Add tickets A and B such that A's query matches B's properties.
  3. Run a matchmaking pass with no cached B -> A result.
  4. Inspect server/matchmaker_process.go and server/matchmaker.go: processDefault calls validateMatch with B's parsed query and A's ticket ID, and validateMatch executes Reader.Search for _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)