bots-go-framework / bots-fw / 29658384797

42%

push

github

feat(router): explicit command-match precedence + opt-in routing tracer

Message routing now applies a FIXED, tiered precedence instead of an emergent,
registration-order-dependent one:

  1. explicit "/command" (and /start <code>, Command.Commands alias)
  2. AwaitingReplyTo (an in-progress flow, e.g. a wizard step)
  3. content matchers: ExactMatch, DefaultTitle, Matcher
  4. no match -> fallback handler / HandleUnmatched

Previously a command's Matcher/ExactMatch/DefaultTitle returned immediately in a
single interleaved loop, so a catch-all Matcher command silently OVERRODE an
active AwaitingReplyTo — hijacking wizard replies (a user answering "What do you
promise to do?" got "Sorry, I did not understand that"). AwaitingReplyTo is now a
dedicated pass BEFORE the content matchers, so a mid-flow reply is never hijacked,
independent of registration order. Explicit commands still outrank an awaiting
reply (so /cancel always escapes a flow).

Also adds RoutingTracer: an opt-in package hook (nil by default = zero overhead)
that reports which command won a text message and by which rule ("awaiting-reply",
"matcher", "no-match", ...) — so "why did my reply route there?" is answerable
without enabling framework-wide debug logging.

The function now documents the precedence contract inline. Tests
(router_precedence_test.go) assert each tier and the tracer; the awaiting-vs-matcher
and awaiting-vs-exactmatch cases fail on the old logic and pass on the new.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019igeTHfp1yexko7TRTmYyC

37 of 37 new or added lines in 2 files covered. (100.0%)

1650 of 5894 relevant lines covered (27.99%)

0.33 hits per line