Plugin Chassis (PR #5651) — Reviewer's Guide

This guide exists because PR #5651 is unusually large (105 files, +48,749 / −32 lines, ~150 commits over three weeks) and was built incrementally by merging several feature branches. Reading it commit-by-commit is not productive. Reading it file-by-file without context is also not productive. This doc gives you a structured walk-through so you can validate each layer independently.

Companion documents:

• ABI.md — the plugin ABI contract: what's stable, what's tail-extensible, how versioning works.
• FILE_CHANGES.md — file-by-file inventory (~140 files described, grouped by area).

For plugin authors who just want to write a plugin, see doc/PLUGIN_API.md. This document is for someone reviewing the plumbing.

1. What this PR does (in one paragraph)

It introduces a plugin chassis — a generic ABI plus a dlopen-based loader inside libproxysql.a — and uses that chassis to ship the first plugin: a MySQL X Protocol terminator that builds as a separate .so. The chassis lives behind #ifdef PROXYSQL40 (a new feature tier; PROXYSQLGENAI now implies it). Under any v3.x build (make with no flags, make PROXYSQL31=1) the chassis is fully invisible — no symbols, no headers, no behaviour change. The mysqlx plugin is the prototype consumer of the chassis; it auths clients, routes queries to a backend MySQL via X Protocol, optionally terminates client TLS / requires backend TLS, pools backend connections, and negotiates zstd / lz4 X Protocol compression.

   ┌─────────────────────────────────────────────┐
   │  proxysql binary                            │
   │  ┌──────────────────────────────────────┐   │
   │  │  libproxysql.a                       │   │
   │  │  ┌────────────────────────────────┐  │   │
   │  │  │  ProxySQL_PluginManager        │  │   │
   │  │  │  (the chassis)                 │  │   │
   │  │  │  - dlopen + RTLD_LOCAL         │  │   │
   │  │  │  - 4-phase lifecycle           │  │   │
   │  │  │  - services injection          │  │   │
   │  │  │  - admin-command dispatch      │  │   │
   │  │  │  - query-hook dispatch         │  │   │
   │  │  └────────────────────────────────┘  │   │
   │  └──────────────────────────────────────┘   │
   └─────────────────────────────────────────────┘
                        │ dlopen
                        ▼
   ┌─────────────────────────────────────────────┐
   │  ProxySQL_MySQLX_Plugin.so                  │
   │  - X Protocol auth + routing + compression  │
   │  - ~5,600 LOC handwritten                   │
   │  - protobuf 3.x (statically vendored zstd,  │
   │    lz4)                                     │
   └─────────────────────────────────────────────┘

The chassis is designed so the same pattern can host other plugins later (PgBouncer-protocol bridge, custom auth plugins, telemetry plugins, etc.) without reopening this PR.

2. Reading orders

Pick one based on your time budget. Each is cumulative — the 2-hour pass continues from where the 30-minute one ends.

30-minute pass: "is this load-bearing?"

Goal: convince yourself the chassis ABI and lifecycle are sane and the v3.x invisibility is real. Don't read mysqlx; trust that it's a consumer.

1. Read §3 (ABI surface) below. Cross-check against ABI.md.
2. Skim include/ProxySQL_Plugin.h — note PROXYSQL_PLUGIN_ABI_VERSION = 3, the descriptor struct (unchanged from ABI 2), the services struct (ABI 3 appends register_runtime_view at the tail).
3. Read §4 (Four-phase lifecycle) below.
4. Skim lib/ProxySQL_PluginManager.cpp lines 324–461 (load + register_schemas + abi_version gating) and 548–576 (stop_all pairs with init).
5. Check the v3.x invisibility claim:
   • grep -L PROXYSQL40 include/ProxySQL_Plugin.h include/ProxySQL_PluginManager.h lib/ProxySQL_PluginManager.cpp should be empty (every chassis file is wrapped).
   • The chassis-related deltas in lib/Admin_Bootstrap.cpp (line ~944) and lib/ProxySQL_Admin.cpp (line ~342) are inside #ifdef PROXYSQL40 blocks.
6. Skim §7 (Seams where consistency could break) below — this is the list of things the incremental development pattern could have left contradictions in. Each item has a one-line check.

2-hour pass: "is this really designed?"

Goal: walk one full request path through the chassis and through mysqlx. Convince yourself the design is coherent end-to-end.

7. Read §5 (Mysqlx as worked example) below.
8. Trace one client connection through the code:
   • Mysqlx_Thread::accept_new_connection() (plugins/mysqlx/src/mysqlx_thread.cpp:200)
   • MysqlxSession::handler() switch (plugins/mysqlx/src/mysqlx_session.cpp:187)
   • handler_capabilities_get() → handler_capabilities_set() (compression + tls negotiation)
   • handler_auth_start() → handle_auth_mysql41() → resolve_backend_target() → send_auth_ok()
   • handler_connecting_server() (mysqlx_session.cpp:1028) — the backend auth handshake
   • handler_waiting_client_msg() / handler_waiting_server_msg() — the steady-state pump
9. Read §6 (Build & CI) below.
10. Verify a v3.0 build still works locally: make clean && make (with no flags). Should produce src/proxysql with no chassis symbols (nm src/proxysql | grep -i plugin_manager should be empty).

Full day: "I'm going to vouch for this on v3.0."

Goal: validate the entire test corpus, run the unit tests, and exercise the e2e against a real MySQL.

11. Read FILE_CHANGES.md end-to-end.
12. Run the test suite per the verification checklist at the end of this doc.
13. Build with PROXYSQLGENAI=1 and run a local mysqlx connection through ProxySQL against a Docker MySQL 8.4. The CI workflow .github/workflows/CI-mysqlx.yml documents the commands.

3. The chassis ABI surface

The chassis is defined by two headers plus the loader implementation. The contract a plugin author sees is everything declared in include/ProxySQL_Plugin.h. The contract the proxysql core sees is everything declared in include/ProxySQL_PluginManager.h.

Key types (in include/ProxySQL_Plugin.h):

• PROXYSQL_PLUGIN_ABI_VERSION (currently 3) — what newly-built plugins target. ABI 1 was the original 6-field descriptor; ABI 2 appends register_schemas for the four-phase lifecycle; ABI 3 keeps the descriptor unchanged and appends register_runtime_view at the tail of ProxySQL_PluginServices so plugins can declare admin-side projections of module state.
• ProxySQL_PluginDescriptor — 7-field struct returned via extern "C" proxysql_plugin_descriptor_v1(). The single mandatory entry point a plugin must export.
• ProxySQL_PluginServices — services struct injected into the plugin: table/command/query-hook registration, log helper, three DB getters, prometheus registry, runtime-view registration. Tail-append discipline preserves ABI compatibility (ABI-2 plugins compile against the smaller layout and still load on an ABI-3 core).

The contract of the descriptor is:

• name is a non-null, non-empty C string. The loader rejects anything else.
• abi_version ∈ [1, PROXYSQL_PLUGIN_ABI_VERSION_MAX]. The loader rejects anything else.
• init, start, stop: function pointers. NULL is permitted (a plugin can opt out of a phase).
• register_schemas: only read when abi_version >= 2. ABI-1 plugins skip Phase B.

See ABI.md for the full contract, including the tail-append rule, the Phase-B-vs-Phase-D services availability matrix, the C++-ABI coupling note (std::string and prometheus-cpp are part of the contract — plugin and core must share toolchain), and the empty-source-sync invariant.

4. The four-phase plugin lifecycle

This is the single most important thing to validate. The lifecycle is implemented in lib/ProxySQL_PluginManager.cpp and driven from src/main.cpp's startup sequence.

startup                                                              shutdown
┌─────┐    Phase A      Phase B           Phase C      Phase D       Phase E      ┌──────────┐
│main │ ─► load ──────► register_schemas ─► admin ────► init ──────► start ──────►│ workers  │
└─────┘    (dlopen)     (declare DDL)     init        (full         (threads      │ running  │
                                          (DDL run)    services)     spawn)       └────┬─────┘
                                                                                       │
                                                                                       ▼
                                                                                      ...
                                                                                       │
                                                                                  shutdown
                                                                                       │
                                                                  ◄─── stop ─────── teardown
                                                                  ◄─── unload (dlclose)

Invariants worth verifying:

1. stop pairs with init, not with start. If init succeeds but start fails, stop still runs. (See lib/ProxySQL_PluginManager.cpp:548–576. Test: plugin_manager_unit-t.cpp:test_multi_plugin_start_failure_stops_started.)
2. Phase D writes commands_/hooks_; workers read them lock-free. Phase D MUST complete before any worker thread reads via proxysql_has_configured_plugin_query_hook. If a future change moves listener startup before Phase D finishes, plain writes race plain reads. (Comment block at lib/ProxySQL_PluginManager.cpp:929–949.)
3. The manager pointer is published BEFORE Admin::init. Admin::init reads tables via proxysql_get_plugin_manager(). If the publish was deferred to after Phase D, the merge would see no plugin tables. (Comment block at the top of proxysql_load_configured_plugins.)
4. register_schemas is only dereferenced when abi_version >= 2. A v1 plugin's struct ends after status_json; reading past would be an out-of-bounds access. (Check at lib/ProxySQL_PluginManager.cpp:407.)
5. The descriptor struct is tail-extensible. A v3.x plugin compiled against ABI 2 still loads in a hypothetical future ABI 3 core (the core ignores the trailing fields it doesn't know; the plugin doesn't care). The reverse — a future plugin against an older core — is rejected at load time by the version check.

5. The mysqlx plugin as worked example

The mysqlx plugin lives entirely under plugins/mysqlx/. It builds as ProxySQL_MySQLX_Plugin.so and is loaded by the chassis at startup.

The state machine is in MysqlxSession (plugins/mysqlx/src/mysqlx_session.cpp, ~1,600 LOC). The 21-state enum Status drives a switch in handler() (line 187). For each Status value there's one handler_*() function. The state-to-handler mapping is in FILE_CHANGES.md area H.

A typical client flow:

client                                              ProxySQL                                         backend
  │                                                    │                                              │
  ├─── TCP connect ───────────────────────────────────►│                                              │
  │                                                    ├─ accept_new_connection                       │
  │                                                    │  → MysqlxSession in CONNECTING_CLIENT        │
  ├─── CapabilitiesGet ──────────────────────────────► ├─ handler_connecting_client                   │
  │ ◄────────────────── caps reply ────────────────────┤  → X_CAPABILITIES_GET → handler_capabilities_get
  ├─── CapabilitiesSet (tls=true,                  ──► ├─ handler_capabilities_set:                   │
  │     compression=zstd_stream)                       │    parse caps, validate compression algo     │
  │ ◄──────────────────── Ok ─────────────────────────┤                                              │
  │ ◄═══ TLS handshake ═══════════════════════════════►│   X_TLS_ACCEPT_INIT / _CONT / _DONE          │
  ├─── AuthenticateStart (mysql41) ─────────────────► ├─ handler_auth_start                           │
  │ ◄────────────── AuthenticateContinue ─────────────┤    (challenge sent)                           │
  ├─── AuthenticateContinue (scramble) ──────────────►├─ handler_auth_challenge_response:             │
  │                                                    │     verify scramble (CRYPTO_memcmp)           │
  │                                                    │     resolve_backend_target() ─── route ──────┤
  │ ◄────────────────── AuthenticateOk ───────────────┤                                              │
  │                                                    │   WAITING_CLIENT_XMSG                        │
  ├─── StmtExecute ─────────────────────────────────► ├─ handler_waiting_client_msg                   │
  │                                                    │     → CONNECTING_SERVER if no backend yet    │
  │                                                    │     → handler_connecting_server: connect +   │
  │                                                    │       backend auth state machine ────────────►├─── X auth handshake
  │                                                    │     → forward_to_backend  ───────────────────►├─── StmtExecute
  │                                                    │                                              │ ◄── Resultset rows
  │                                                    │   handler_waiting_server_msg                 │
  │                                                    │     → forward_frame_to_client                │
  │                                                    │     → send_to_client_compressed              │
  │ ◄────────────── (zstd-compressed) Resultset ──────┤                                              │
  │                                                    │   WAITING_CLIENT_XMSG                        │
  │                                                    │  (loop)                                      │

The mysqlx plugin demonstrates every chassis affordance:

• Phase B — mysqlx_register_schemas declares 8 admin-schema tables (mysqlx_users, mysqlx_routes, mysqlx_backend_endpoints, mysqlx_variables, plus their runtime_* admin-side projections and stats_mysqlx_* tables), 16 admin commands (LOAD MYSQLX USERS TO RUNTIME and the 7 cousins, plus SAVE variants and aliases like FROM MEMORY / FROM MEM / TO RUN), and four runtime-view refresh callbacks via services.register_runtime_view (one per runtime_mysqlx_<X> table).
• Phase D — mysqlx_init performs disk-to-memory sync of the mysqlx tables on first boot, then loads the in-memory MysqlxConfigStore directly from the editable admin tables via four install_<X>_from_admin calls.
• Phase E — mysqlx_start clamps the thread-pool size, drives the listener reconciler from MysqlxConfigStore::snapshot_active_routes(), and spawns N worker threads.
• Admin command dispatch — LOAD MYSQLX <X> TO RUNTIME lands on a callback that invokes MysqlxConfigStore::install_<X>_from_admin; SAVE MYSQLX <X> [FROM RUNTIME] TO MEMORY invokes MysqlxConfigStore::save_<X>_to_admin_table. The disk-tier variants (LOAD/SAVE FROM/TO DISK) remain a plain BEGIN/DELETE/INSERT/COMMIT between configdb and admindb.
• Runtime-view projections — when admin runs SELECT * FROM runtime_mysqlx_users (or one of the four cousins), the chassis fires the registered refresh callback, which calls MysqlxConfigStore::project_<X>_to_runtime_view(admindb) to wipe and refill the admin table from current module state.
• Identity callbacks — each MysqlxSession is given an identity_lookup_ closure that calls back into MysqlxConfigStore::resolve_identity() for the username the client sends.

If you can convince yourself the chassis can host the mysqlx plugin coherently, the chassis is in good shape.

6. Build & CI tier-flag wiring

PROXYSQL40=1 must propagate consistently through five Makefile layers. A mismatch silently changes the descriptor / services struct layouts between core and plugin — the link succeeds, the first dispatch corrupts memory.

top-level Makefile
   │  PSQL40 := -DPROXYSQL40 (when PROXYSQL40=1)
   │
   ├─► lib/Makefile     (compiles ProxySQL_PluginManager.cpp into libproxysql.a)
   ├─► src/Makefile     (links libproxysql.a)
   ├─► plugins/mysqlx/Makefile   (compiles ProxySQL_MySQLX_Plugin.so)
   └─► test/tap/tests/unit/Makefile  (compiles plugin_*_unit-t / mysqlx_*_unit-t)
                                      adds -DMYSQLX_TEST_BUILD on top

Verifications:

• nm src/proxysql | grep -i ProxySQL_PluginManager is empty when built without PROXYSQL40=1.
• nm src/proxysql | grep -i ProxySQL_PluginManager is non-empty when built with PROXYSQLGENAI=1 (which implies PROXYSQL40=1).
• The mysqlx plugin Makefile fails fast if libprotobuf is not 3.x (see plugins/mysqlx/Makefile:38–51). Already saw this fire on CI in commit 9f5ed235b — the cleanbuild path triggered the check on a v3.0 box without libprotobuf-dev. Fixed by skipping the check on clean/cleanall.
• CI workflow .github/workflows/CI-mysqlx.yml invokes make inside plugins/mysqlx with all five tier flags explicitly: PROXYSQL40=1 PROXYSQL31=1 PROXYSQLFFTO=1 PROXYSQLTSDB=1 PROXYSQLGENAI=1. This was added in commit df7e335e2 after the tests/CI agent caught that the workflow was building the plugin with a different set of tier flags than the cached src/proxysql had been built with — exactly the silent struct-layout-mismatch hazard.

7. Seams where consistency could break

These are the places where the incremental development pattern could have left contradictions — a comment that says one thing while the code does another, two paths that claim to do the same job, an #ifdef that forgot to flip somewhere. Each item has a one-line verification.

If all 17 of these check, the consistency concern is largely answered — the pieces line up.

8. Commit topology

The PR has ~150 commits, but they group naturally into five intent-bands. You don't need to review individually; you need to know which commits drove which design.

Band 1 — chassis foundation (early April)

The original design + initial implementation. These set the ABI shape.

• 7e1a12b8f feat: add generic plugin ABI and loader
• da7e18271 fix: align plugin loader ABI and tests
• f13463d33 feat(plugin-abi): Step 2.2 — four-phase plugin lifecycle
• cd15afdd1e feat: support plugin-owned admin tables and commands
• 2430516600 fix: reject conflicting plugin registrations

If you only read 5 commits, read these.

Band 2 — mysqlx baseline (early-to-mid April)

The X Protocol plugin built on top of the chassis. ~80 commits, mostly within plugins/mysqlx/. These are the "feature work" commits and are best reviewed by reading the result, not the patches — see FILE_CHANGES.md area A–L.

Band 3 — mysqlx hardening (mid-to-late April)

Bug fixes from running the plugin against a real MySQL 8.4. These are the small surgical commits — the kind you'd cherry-pick if you needed to backport a fix.

• 7e2f7828a fix(mysqlx): make sync transactions atomic on execute() failure
• c78d7b859 fix(mysqlx): reconcile bind-address changes
• dd131b0aa fix(mysqlx): reconcile listeners at startup and on LOAD ROUTES TO RUNTIME
• 3e8c3da9d fix(mysqlx): preserve backend TLS state past auth handshake
• 82fe27f4b fix(mysqlx): sync empty source tables to overwrite stale rows
• e09908179 fix(mysqlx): record stats on unreachable guard
• 76aafdac6 fix(mysqlx): harden check_connect() poll and getsockopt handling
• bbe812251 fix(mysqlx): reject auth without credential_lookup and release pooled fd

Band 4 — chassis hardening + invisibility audit (April 19–22)

After the original design landed, an audit found symbols leaking into v3.x and dead code paths. These commits clean that up.

• 3ba92815f fix(plugin-chassis): make chassis fully invisible in v3.x builds
• ab9d5a103 fix(plugin-chassis): address deep-review findings
• 6edde821c fix(glovars): forward-declare debug_level for direct header consumers
• e20876a45 fix(tests): repair pre-existing mysqlx test build breakage
• f10411692 fix(plugin-mgr): serialize lifecycle and always reset manager on stop

Band 5 — review-driven cleanup (this week, April 27)

The independent review of PR #5651 produced 19 findings. These commits address them.

• 9f5ed235b fix(build,test groups): unblock CI on plugin-chassis (B3 + #6 + lint)
• 4bd4b462b fix(mysqlx): three blocking protocol/pool correctness bugs (B1 + B2 + parse)
• 04bccec51 chore(plugin-chassis): tighten gating, drop dead paths, gate forgery setters (#9 + #10 + #12 + #13)
• df7e335e2 fix(ci,infra): pass PROXYSQL40 to plugin build, remove orphaned infra files (#5 + #4 + #18)
• 55e90d1a7 fix(plugin-chassis,mysqlx): chassis read-path scaling, graceful shutdown, hardening (#7 + #8 + #11 + #15 + #16 + #17)

For a complete walk through each finding and how it was addressed, see git log --grep="PR #5651" --since=2026-04-26.

9. Verification checklist

A reviewer who can tick each box has done a fair-quality review of this PR.

Build

• make clean && make (no flags) succeeds on a v3.0-grade box. nm src/proxysql | grep ProxySQL_PluginManager is empty.
• make clean && PROXYSQLGENAI=1 make succeeds. nm src/proxysql | grep ProxySQL_PluginManager is non-empty.
• cd plugins/mysqlx && PROXYSQL40=1 PROXYSQL31=1 PROXYSQLFFTO=1 PROXYSQLTSDB=1 PROXYSQLGENAI=1 make produces ProxySQL_MySQLX_Plugin.so.
• nm plugins/mysqlx/ProxySQL_MySQLX_Plugin.so | grep -i 'visibility\|hidden' shows hidden visibility default; only proxysql_plugin_descriptor_v1 exported.

ABI hygiene

• 32 plugin/mysqlx test entries carry @proxysql_min_version:4.0; verify with the grep in §7 row 13.
• python3 test/tap/groups/lint_groups_json.py returns OK.
• python3 test/tap/groups/check_groups.py returns OK.

Tests

• make build_tap_tests succeeds with PROXYSQLGENAI=1.
• At least one of the larger unit tests passes: cd test/tap/tests/unit && ./mysqlx_robustness_unit-t should report 74/74.
• ./plugin_lifecycle_unit-t, ./plugin_dispatch_unit-t, ./plugin_query_hook_unit-t all green.

Sanity (manual)

• Start ProxySQL with PROXYSQLGENAI=1 build, plugins=("/path/to/ProxySQL_MySQLX_Plugin.so") in proxysql.cnf, and the mysqlx_users / mysqlx_routes tables populated.
• Connect with mysqlsh --mysqlx --uri user@host:6033 (or X-Protocol port from your config). A handshake completes; a SELECT 1 round-trips.
• SELECT * FROM stats_mysqlx_routes shows non-zero counters.
• SHUTDOWN — the client sees a clean disconnect, not a TCP RST. (This validates shutdown_notify_client() from §7 row 10.)

Consistency seams (§7)

• All 17 rows from §7 verified.

If a reviewer ticks all of the above, this PR has been substantively reviewed.

Appendix: how this PR was assembled

For full transparency, the mysqlx plugin started as PR #5593 (ProtocolX branch) targeting v3.0 directly. The chassis started as PR #5651 (plugin-chassis branch) also targeting v3.0. PR #5593 was retargeted onto plugin-chassis and merged there, so the chassis PR (#5651) now carries both. This is why the commit history includes a mix of "chassis foundation" commits and "mysqlx feature/fix" commits — they were two PRs unified into one for review purposes, since the mysqlx plugin doesn't make sense without the chassis underneath it.

The independent review described in Band 5 above produced this guide as a deliverable.