brbzull0 opened a new pull request, #13146: URL: https://github.com/apache/trafficserver/pull/13146
Adds a small `TSCfg*` plugin-facing API that lets plugins register configuration files with the same reload framework core configs already use (`ConfigRegistry` / `ConfigContext`). Plugin reloads then surface in `traffic_ctl config status` with full state tracking, can receive RPC payloads, and follow the deferred-completion contract - none of which were available via `TSMgmtUpdateRegister`. ## Motivation Today, plugins react to `traffic_ctl config reload` only via `TSMgmtUpdateRegister`. That gives them a notification but nothing else: no per-key targeting, no payload, no `_reload` directives, no companion files, no way to surface reload outcome in `config status`. Every plugin that wants config-reload behaviour ends up re-implementing pieces of the framework - `regex_revalidate`, for example, ships its own file-mtime watcher. This PR exposes the framework directly so plugins integrate with it instead of re-implementing it. ## New API surface ### Types & enums (in [`include/ts/apidefs.h.in`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in)) - [`TSCfgLoadCtx`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1595) — opaque per-reload handle. - [`TSCfgLoadCb`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1597-L1613) — plugin reload callback signature. - [`TSCfgSourceType`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1615-L1619) — `FILE_ONLY` / `FILE_AND_RPC`. - [`TSCfgLogLevel`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1621-L1632) — `NOTE` / `WARNING` / `ERROR`. - [`TSCfgRegistrationInfo`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1652-L1689) — option struct for `TSCfgRegister`. - [`TSCfgFileDependencyInfo`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1712-L1735) — option struct for `TSCfgAddFileDependency`. - [`TSYaml`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/apidefs.h.in#L1739) — opaque alias for `YAML::Node*` (pre-existing JSONRPC type, reused). ### Registration (called from `TSPluginInit`) | Function | Declaration | Implementation | |---|---|---| | `TSCfgRegister` | [`ts.h:1285`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1285) | [`InkAPI.cc:3335`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3335) | | `TSCfgAttachReloadTrigger` | [`ts.h:1330`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1330) | [`InkAPI.cc:3409`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3409) | | `TSCfgAddFileDependency` | [`ts.h:1347`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1347) | [`InkAPI.cc:3435`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3435) | ### Per-reload context (used inside the plugin's `TSCfgLoadCb`) | Function | Declaration | Implementation | |---|---|---| | `TSCfgLoadCtxInProgress` | [`ts.h:1371`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1371) | [`InkAPI.cc:3519`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3519) | | `TSCfgLoadCtxComplete` | [`ts.h:1384`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1384) | [`InkAPI.cc:3535`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3535) | | `TSCfgLoadCtxFail` | [`ts.h:1397`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1397) | [`InkAPI.cc:3541`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3541) | | `TSCfgLoadCtxAddLog` | [`ts.h:1412`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1412) | [`InkAPI.cc:3547`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3547) | | `TSCfgLoadCtxAddSubtask` | [`ts.h:1427`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1427) | [`InkAPI.cc:3572`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3572) | | `TSCfgLoadCtxGetFilename` | [`ts.h:1460`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1460) | [`InkAPI.cc:3596`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3596) | | `TSCfgLoadCtxGetReloadToken` | [`ts.h:1476`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1476) | [`InkAPI.cc:3608`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3608) | | `TSCfgLoadCtxGetSuppliedYaml` | [`ts.h:1490`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1490) | [`InkAPI.cc:3620`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3620) | | `TSCfgLoadCtxGetReloadDirectives` | [`ts.h:1503`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/include/ts/ts.h#L1503) | [`InkAPI.cc:3636`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/src/api/InkAPI.cc#L3636) | ## What this gives plugins, on top of `TSMgmtUpdateRegister` - **Per-key targeting** - handler runs only when this plugin's registered file or trigger record actually changes. - **RPC payload** - configs registered with `TS_CFG_SOURCE_FILE_AND_RPC` receive YAML content via JSONRPC and react to `_reload` directives. - **Status surface** - success / fail / in-progress / timeout plus log entries appear in `traffic_ctl config status` for `config reload`, file changes, and record changes during a reload cycle. - **Subtasks** - handlers can split work into named subtasks that aggregate into the parent's status. - **Companion files** - `TSCfgAddFileDependency` declares an extra file whose changes invoke the same handler, optionally routing inline RPC content via `dep_key`. - **Deferred completion** - handlers may stash the context, return, and finish on another thread later. Same contract core handlers already have. ## Limitations - Not supported in remap plugins (`TSRemapInit` / `TSRemapNewInstance`); the reload framework is centred on global plugins. - `is_required` is propagated to `FileManager` but not enforced at reload time today (catalog/inspection only). - `TSCfgAttachReloadTrigger` is not a free-form record-change subscription; it triggers a reload of the registered config and nothing else. ## Documentation - New reference page: [`doc/developer-guide/api/functions/TSCfgRegister.en.rst`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/doc/developer-guide/api/functions/TSCfgRegister.en.rst) consolidates `TSCfgRegister`, `TSCfgAttachReloadTrigger`, `TSCfgAddFileDependency`, and the full `TSCfgLoadCtx*` family. - New section in [`doc/developer-guide/config-reload-framework.en.rst`](https://github.com/brbzull0/trafficserver/blob/plugin-config-registry-api-v2/doc/developer-guide/config-reload-framework.en.rst) covering plugin reload, with example, lifecycle, and `traffic_ctl config status` output. Fixes: #12967 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
