Add COM_QUERY query-rule action for permanent fast-forward

Merged
RE
2mo ago
+1282-10

Summary

Add a strict switch_to_fast_forward Boolean action to MySQL query-rule attributes and consume it only for non-mirror COM_QUERY traffic.

The complete query-rule chain runs first. Its final destination hostgroup is then handed to the existing permanent fast-forward state machine, and the triggering query is forwarded exactly once.

Deliberately narrow protocol scope

  • Only COM_QUERY can consume the action.
  • Mirror sessions never consume it, preventing the mirror-session crash path.
  • Compressed frontend sessions receive error 1815 and are closed. This PR does not translate compressed protocol traffic.
  • COM_STMT_PREPARE, COM_STMT_EXECUTE, replication commands, EOF capability matching, and existing connection/data-stream behavior remain unchanged.
  • Uncompressed COM_QUERY messages crossing the 0xFFFFFF payload boundary are reconstructed with sequential MySQL packet headers and the required exact-multiple terminator before raw fast-forward handoff.

Query-rule behavior

  • Parse switch_to_fast_forward as a strict JSON Boolean.
  • Keep a matched true action sticky through the rest of the rule chain.
  • Leave false, absent, and invalid values disabled.
  • Reset the output action between commands so it cannot leak into later decisions.
  • Preserve normal rule hit accounting and final destination-hostgroup selection.

Validation

  • query_processor_unit-t: 276/276
  • test_query_rule_fast_forward-t on existing mysql84-g9: 32/32
  • reg_test_fast_forward_split_packet-t on existing mysql84-g2: 35/35
  • Historical COM_BINLOG_DUMP and COM_REGISTER_SLAVE regressions on existing mysql84-binlog-g1: 2/2
  • Clean DEBUG + ClickHouse build
  • TAP group format, source-registration, and workflow-coverage lints

The focused E2E test covers ordinary switching, mirror safety, PREPARE/EXECUTE non-consumption, a genuinely compressed client rejection, an uncompressed query larger than 16 MiB with exactly-once execution, subsequent connection liveness, and exact fixture restoration.

Refs #6146. This PR intentionally implements the narrower COM_QUERY-only design approved after that issue was written; it does not close the broader tracking issue.

Summary by cubic

Finalizes ProxySQL-owned query state before the permanent fast-forward handoff and keeps converted COM_FIELD_LIST requests on the normal path.

Adds a strict switch_to_fast_forward Boolean to MySQL query rules. Matching uncompressed COM_QUERY sessions switch permanently to fast-forward: the complete rule chain runs, and its final destination hostgroup is handed to the existing permanent fast-forward state machine.

Protocol scope

  • Only non-mirror COM_QUERY can consume the action; mirrored and converted COM_FIELD_LIST requests never enter fast-forward.
  • Compressed and pipelined frontend transitions are rejected with error 1815 and the session is closed.
  • A dedicated handoff helper finalizes parser, processlist query-pointer, command-marker, query-processor output, and user-variable state before packet ownership moves, so processlist readers never dereference a freed trigger packet.
  • Uncompressed messages crossing the 0xFFFFFF payload boundary are reconstructed with sequential packet headers and the exact-multiple terminator before handoff; COM_STMT_PREPARE, COM_STMT_EXECUTE, and replication commands are unchanged.

Query-rule behavior

  • switch_to_fast_forward is parsed as a strict JSON Boolean; false, absent, and invalid values stay disabled.
  • A matched true action stays sticky through the rest of the rule chain and resets between commands.
  • Normal hit accounting and destination-hostgroup selection are preserved.

Summary by CodeRabbit

  • New Features

    • Added a query-rule option to switch matching MySQL sessions into fast-forward mode.
    • Supports large, multi-packet queries and rule-defined destination hostgroups.

  • Bug Fixes

    • Prevents unsupported fast-forward transitions for compressed sessions, prepared statements, mirror execution, and converted field-list requests.
    • Rejects transitions with buffered pipelined packets.
    • Safely clears query state during fast-forward handoff.

  • Tests

    • Added integration and unit coverage for routing, large queries, handoff safety, and rule parsing.