3 Commits (6cdd4e697eb86982e3dfd2ceab009ead5da0efcb)

Author	SHA1	Message	Date
Rene Cannao	29ee30daf9	docs(plugin-chassis): address PR-#5690 review feedback ... CodeRabbit + Gemini review pass surfaced four small doc-precision items, all legitimate. None were code bugs. # CodeRabbit (markdownlint nit) - doc/PLUGIN_API.md:455: fenced code block at "DISK ↔ MEMORY ↔ RUNTIME" lacked a language specifier. Added `text` to satisfy MD040 / fenced-code-language. # Gemini (3x same root: clarify the matching algorithm) The chassis dispatch matcher is case-insensitive whole-identifier substring match, but three docs described it loosely. Plugin authors deciding what table name to register need to know that runtime_X does not match runtime_X_extra or stats_runtime_X. - doc/PLUGIN_API.md:289 ("any admin SELECT against it") -> spell out the whole-identifier rule with the longer-prefix / longer-suffix rejection examples. - doc/plugin-chassis/ABI.md:156 ("appears in the SQL") -> "is referenced as a whole identifier in the SQL query (case-insensitive; identifier-aware, so runtime_X_extra or stats_runtime_X do not match runtime_X)". - doc/plugin-chassis/FILE_CHANGES.md:102 ("substring match") -> "case-insensitive whole-identifier substring match", matching the precise wording already used in section B for the sql_references_table_ci helper. Cross-section consistency. No source code touched. No new content sections, only existing prose tightened.	2 months ago
Rene Cannao	64e7334297	docs(plugin-chassis): align FILE_CHANGES/ABI/REVIEW_GUIDE/PLUGIN_API with PR #5688 ... The four chassis docs still described the pre-fix architecture: - ABI version 2 (now 3 — register_runtime_view appended at services tail) - MysqlxConfigStore::load_from_runtime (removed; replaced by per-entity install/save/project triplets) - copy_table / copy_to_runtime as the LOAD/SAVE shovels (deleted) - Listener reconciler reading runtime_mysqlx_routes (now reads MysqlxConfigStore::snapshot_active_routes) - "Three-tier" disk/memory/runtime model with the empty-source-sync invariant applied uniformly (the runtime tier was wrong; runtime_<X> is now an admin-side projection of module state, not a tier; the invariant only applies to disk-tier copies) - Plugin-context layout listing a non-existent MysqlxStatsStore Updates per file (no source code touched): - FILE_CHANGES.md §A: PROXYSQL_PLUGIN_ABI_VERSION 2 → 3, services list gains register_runtime_view, ProxySQL_PluginRuntimeView struct documented, separation-of-duties contract spelled out. §B: PluginManager methods list gains register_runtime_view, refresh_runtime_views_for_query; service trampolines list gains register_runtime_view_service; sql_references_table_ci whole-identifier match described; services_phase_b_ wiring of register_runtime_view explained. §C: new pre-SELECT runtime-view dispatch site in GenericRefreshStatistics described — gated on if (admin), OUTSIDE the if (refresh==true) block, so any admin-port query gets the chassis dispatcher fired. §H: mysqlx_start() no longer does runtime sync; describes the four install_<X>_from_admin calls in their place. §I: copy_table removed from the description; new LOAD/SAVE callbacks calling MysqlxConfigStore install/save APIs; four refresh_<X>_runtime_view callbacks registered via services.register_runtime_view(). §J: MysqlxConfigStore reframed as the canonical source of truth (runtime_mysqlx_<X> are projections of it). API list replaced load_from_runtime with the four install/save/ project triplets, install_all_from_admin (test convenience), snapshot_active_routes, and MysqlxBackendEndpointOverride. §K: listener reconciler reads MysqlxConfigStore directly via snapshot_active_routes(); inline rationale notes why we must NOT read runtime_mysqlx_routes (empty between LOAD calls under the new architecture). - ABI.md: services availability matrix gains register_runtime_view (live in Phase B and D); current-ABI block 3/3; §5 retitled "Separation of duties" with the new contract; disk-tier exception keeps the empty-source-sync invariant. - REVIEW_GUIDE.md: ABI-surface bullets updated; mysqlx phase descriptions updated to point at install_*_from_admin / runtime-view projections / snapshot_active_routes-driven reconciler. - PLUGIN_API.md: descriptor table updated for ABI 3; services struct snippet shows the ABI-2 and ABI-3 tail extensions; new register_runtime_view callback section with the contract; "Three-Tier" section retitled "Separation of duties", clarifies that runtime_<X> is an admin-side projection (not a persistent tier) and the empty-source-sync invariant applies only to disk- tier copies; alias-handling note corrected. The only surviving "ABI version 2" mention is in PLUGIN_API.md line 46 ("plugins that declare ABI version 2 or higher") — that is a correct version-or-higher predicate, not a stale reference.	2 months ago
Rene Cannao	42afebcb64	docs(plugin-chassis): add reviewer's guide, ABI contract, and file inventory ... PR #5651 is large enough that reading commit-by-commit or file-by-file without context is unproductive. Add three companion docs under doc/plugin-chassis/ so a senior reviewer can validate the PR layer by layer. * REVIEW_GUIDE.md (~345 lines) — entry point. One-paragraph project description, scope diagram, three reading orders (30 minutes / 2 hours / full day), the 4-phase plugin lifecycle with a sequence-style ASCII diagram, the worked-example walk-through of a mysqlx client request end to end, the build-system tier-flag propagation map (5 Makefile layers), 17 explicit "consistency seams" each with a one-line shell verification, the 5 commit-intent bands so the ~150 commits map to a small number of logical changes, and a final verification checklist. * ABI.md (~270 lines) — the canonical reference for the plugin ABI: the descriptor surface, the services surface and its phase-availability matrix, the C++-ABI coupling (std::string and prometheus-cpp must match between core and plugin), the empty-source-sync invariant, the concurrency model and lifecycle pairing rules ("stop pairs with init, not start"), the ABI versioning rules (tail-append, version-gate every new-field read, reject anything > MAX), and a minimal plugin skeleton for reference. * FILE_CHANGES.md (~503 lines) — the per-file inventory. Sections A–G cover the chassis core (15 files), H–S cover the mysqlx plugin (12 source files + 1 build file + 16 generated protobuf files described collectively), T covers tests/CI/infra (28 unit tests with their individual plan() counts, 4 integration tests, the build glue, the groups.json delta, and the new CI workflow). Each entry: path, status, line-count, purpose, key contents, what to spot-check. Total: 1117 lines of reviewer documentation. The expectation is that a reviewer with 30 minutes can ship-no-ship from REVIEW_GUIDE alone; a reviewer with 2 hours can validate the architecture; a reviewer with a full day can run every test and walk every file via FILE_CHANGES. These docs are written for THIS PR. They are not a replacement for doc/PLUGIN_API.md (which is the public-facing API doc for plugin authors) — REVIEW_GUIDE explicitly points at PLUGIN_API for plugin authors and at ABI.md for the canonical contract. Verified: - All 17 §7 verification rows actually pass on the current HEAD (spot-checked: register_schemas gating at abi_version >= 2, TLS_PASSTHROUGH absence, shared_mutex change, ABI version macros, groups.json tag counts). - Cross-doc references (REVIEW_GUIDE → ABI → FILE_CHANGES) are consistent.	2 months ago