Add a query-rule action to switch a MySQL session to fast-forward mode

Summary

Add a production-supported MySQL query-rule action that permanently switches a matched client session from normal ProxySQL processing into fast-forward mode.

The action is configured through mysql_query_rules.attributes:

{"switch_to_fast_forward": true}

This is a fresh implementation targeting v3.0. PR #4449 is an old proof of concept and must not be cherry-picked.

Motivation

ProxySQL fast-forward is currently selected per user through mysql_users.fast_forward. A query-rule action makes the decision context-sensitive using all normal rule predicates, including:

• listening proxy_port;
• username and schema;
• client/proxy address;
• digest or pattern;
• flags and rule chaining.

The same user can use normal ProxySQL routing on one interface and permanent fast-forward on another. The matching rule can select any destination_hostgroup: the current/default hostgroup, a different hostgroup, or the result of a complete rule chain.

The immediate consumer is the production MySQL Router replacement plugin tracked by PR #6144, but this feature is generic and Router-independent.

Required semantics

1. Parse switch_to_fast_forward from query-rule attributes with strict validation.
2. A true action becomes sticky when its rule matches; false or absent leaves the session in normal mode.
3. The action may match at any query-processing point in the session. It is not limited to the first command or to a pristine session.
4. Complete the normal rule chain and use its final routing decision, including the final destination_hostgroup.
5. Switch before sending the triggering command and forward that command exactly once.
6. Transition permanently to SESSION_FORWARD_TYPE_PERMANENT.
7. Use the backend connection selected by normal ProxySQL session/routing state and retain it as the dedicated fast-forward backend.
8. Bypass query rewriting, caching, multiplexing, and subsequent query-rule processing after the transition.
9. Preserve existing user-level mysql_users.fast_forward behavior.
10. Preserve TLS, compression, timeout, backend-offline, and graceful-close behavior already supported by permanent fast-forward sessions.
11. Record the transition rule hit once; later commands do not increment query-rule hit counters.
12. Do not add a ProxySQL-side timing or session-state restriction to the action.

A useful pattern is to switch on a statement that already makes the connection stateful, for example BEGIN or CREATE TEMPORARY TABLE.

Prepared statements

The action is not rejected or blocked when the client or any backend connection associated with the session already has prepared statements.

At transition time ProxySQL emits one warning when the frontend or any backend connection associated with the session has prepared-statement state. The warning identifies the frontend connection/session and whether client-side, backend-side, or both kinds of state were detected. It must not expose SQL text, credentials, or other secrets.

Documentation advises operators to switch to fast-forward before creating prepared statements. This is guidance, not an enforced restriction.

Configuration example

INSERT INTO mysql_query_rules
  (active, proxy_port, destination_hostgroup, apply, attributes, comment)
VALUES
  (1, 6446, 10, 1, '{"switch_to_fast_forward":true}',
   'fast-forward connections arriving on this route');

LOAD MYSQL QUERY RULES TO RUNTIME;

Operators can disable conversion by removing the attribute or setting it to false, and can independently change destination_hostgroup.

Acceptance tests

• Attribute parsing: true, false, absent, malformed type, and malformed JSON.
• Rule chaining and final destination-hostgroup selection.
• Match by proxy_port with the same user remaining in normal mode on another port.
• Same and different destination hostgroups.
• Transition after earlier normally processed queries.
• Rules matching BEGIN and CREATE TEMPORARY TABLE.
• Triggering COM_QUERY executes exactly once.
• Transition is permanent and subsequent query rules are bypassed.
• Existing client or session-backend prepared-statement state does not block conversion and emits exactly one advisory warning.
• No prepared-statement warning when neither side has prepared-statement state.
• Plain, frontend/backend TLS, and compression connections.
• Backend connect failure and backend becoming OFFLINE.
• Query-rule hit counters stop changing after conversion.
• Normal behavior when the action is false or absent.
• Existing per-user fast-forward regression coverage.
• FFTO compatibility without allowing observation to affect routing.

Documentation

Document the attribute, permanent transition lifetime, at-any-time semantics, interaction with destination_hostgroup, rule chaining, user-level fast-forward, multiplexing, prepared-statement guidance/warning, and FFTO.

Out of scope

• MySQL Router ports or bootstrap defaults.
• Routing Guidelines.
• Plugin-specific hostgroup ownership.
• Changes to mysql_users.fast_forward.