You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@trafficserver.apache.org by "brbzull0 (via GitHub)" <gi...@apache.org> on 2026/05/08 11:46:55 UTC
[PR] [TS API] Add plugin API for the config reload framework. [trafficserver]
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#discussion_r3734303066
##########
src/api/InkAPI.cc:
##########
@@ -3310,6 +3316,414 @@ TSMgmtUpdateRegister(TSCont contp, const char *plugin_name, const char *plugin_f
global_config_cbs->insert(reinterpret_cast<INKContInternal *>(contp), plugin_name, plugin_file_name);
}
+////////////////////////////////////////////////////////////////////
+//
+// Config Registry - plugin config reload registration
+//
+////////////////////////////////////////////////////////////////////
+
+namespace
+{
+// Handle behind the opaque TSCfgLoadCtx. One is created per handler invocation
+// (and per subtask) and owned by PluginCtxRegistry. Caches the strings/nodes the
+// getters need to return as stable pointers for the lifetime of the handle.
+struct PluginConfigContext {
+ ConfigContext ctx;
+ std::string filename;
+ std::string reload_token;
+ YAML::Node supplied_yaml;
+ YAML::Node reload_directives;
+};
+
+DbgCtl dbg_ctl_plugin_config{"config.reload"};
+
+// Process-lifetime registry of live TSCfgLoadCtx handles.
+//
+// Handles handed to plugins are opaque monotonically-increasing ids, never raw
+// pointers, so a stale handle can never alias a freshly-allocated context (no
+// ABA). Every accessor validates the id under the registry lock, so a call made
+// after Complete/Fail - or on a bogus handle - is a genuine no-op instead of a
+// use-after-free read. Complete/Fail extract (and thus free) the context under
+// the same lock, so a second finalize can never double-free.
+class PluginCtxRegistry
+{
+public:
+ static PluginCtxRegistry &
+ instance()
+ {
+ static PluginCtxRegistry r;
+ return r;
+ }
+
+ /// Take ownership of @a pctx and return its opaque handle.
+ TSCfgLoadCtx
+ create(std::unique_ptr<PluginConfigContext> pctx)
+ {
+ std::lock_guard lock(_mutex);
+ uint64_t id = _next_id++;
+ _live.emplace(id, std::move(pctx));
+ return reinterpret_cast<TSCfgLoadCtx>(static_cast<uintptr_t>(id));
+ }
+
+ /// Look up a live context by handle. Returns @c nullptr when the handle was
+ /// already finalized or was never valid. The returned pointer stays owned by
+ /// the registry; callers must use it only within the (single-threaded per
+ /// handle) plugin contract.
+ PluginConfigContext *
+ lookup(TSCfgLoadCtx handle)
+ {
+ uint64_t id = static_cast<uint64_t>(reinterpret_cast<uintptr_t>(handle));
+ std::lock_guard lock(_mutex);
+ auto it = _live.find(id);
+ return it != _live.end() ? it->second.get() : nullptr;
+ }
Review Comment:
PluginCtxRegistry::lookup() returns a raw PluginConfigContext* after releasing the registry mutex. All TSCfgLoadCtx* APIs then dereference this pointer without holding any lifetime guarantee. If a plugin calls TSCfgLoadCtxComplete/Fail on another thread while a different thread is in (or about to enter) TSCfgLoadCtxAddLog/InProgress/Get* for the same handle, extract() can free the context and the other thread can hit a use-after-free.
Given the API explicitly supports deferred completion from another thread, the handle operations should be safe under concurrent use (even if plugins misbehave occasionally). Consider returning a shared ownership token from the registry (e.g., store std::shared_ptr<PluginConfigContext> in _live and have lookup() return a shared_ptr), or providing a registry method that executes an accessor under the mutex so the context cannot be freed mid-call.
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#issuecomment-5236808307
Hi @cmcfarlen, thanks for the review, I made some changes base on your feedback. thanks.
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#issuecomment-5233140691
[approve ci freebsd]
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for the config reload framework. [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#discussion_r3208501875
##########
src/mgmt/config/ConfigRegistry.cc:
##########
@@ -426,6 +480,28 @@ ConfigRegistry::schedule_reload(const std::string &key)
eventProcessor.schedule_imm(new ScheduledReloadContinuation(mutex, key), ET_TASK);
}
+void
+ConfigRegistry::apply_passed_config(ConfigContext &ctx, YAML::Node &passed_config, std::string_view key)
+{
+ // Extract _reload directives before passing content to the handler. This keeps
+ // supplied_yaml() clean (pure config data) and exposes reload_directives() as a
+ // separate accessor for operational parameters.
+ if (passed_config.IsMap() && passed_config["_reload"]) {
+ auto directives = passed_config["_reload"];
+ if (!directives.IsMap()) {
+ Warning("Config '%.*s': _reload must be a YAML map, ignoring directives", static_cast<int>(key.size()), key.data());
+ } else {
+ Dbg(dbg_ctl, "Config '%.*s' has reload directives", static_cast<int>(key.size()), key.data());
+ ctx.set_reload_directives(directives);
+ }
+ passed_config.remove("_reload");
Review Comment:
In apply_passed_config(), `passed_config["_reload"]` uses yaml-cpp's non-const operator[] which inserts the key when missing. That mutates the RPC payload and can cause `_reload` to appear (as an Undefined node) in the content passed to handlers, violating the documented contract that `_reload` is stripped from supplied_yaml. Use a const lookup (or other non-inserting check) before deciding whether to extract/remove `_reload`.
##########
doc/developer-guide/api/functions/TSCfgRegister.en.rst:
##########
@@ -0,0 +1,561 @@
+.. Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSCfgRegister
+*************
+
+Register a plugin's configuration file with the |TS| reload framework
+and drive the per-reload context object delivered to the handler.
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+ #include <ts/ts.h>
+
+.. enum:: TSCfgSourceType
+
+ What content sources a plugin's config handler supports.
+
+ .. enumerator:: TS_CFG_SOURCE_FILE_ONLY
+
+ Handler reloads only from a file on disk. RPC-supplied YAML is
+ rejected.
+
+ .. enumerator:: TS_CFG_SOURCE_FILE_AND_RPC
+
+ Handler can also process YAML content supplied via RPC.
+
+.. type:: TSCfgRegistrationInfo
+
+ Options struct passed to :func:`TSCfgRegister`. Fields are set with
+ C++20 designated initializers; new fields may be appended in future
+ |TS| versions without breaking source compatibility for existing
+ plugins.
+
+ .. var:: std::string_view key
+
+ Unique registry key, also used as the YAML node name when an
+ operator reloads via
+ ``traffic_ctl config reload --data '{<key>: {...}}'``.
+ Must be unique across all registered configs (core and plugin).
+
+ **Convention.** Use the plugin name (``my_plugin``). Keep the key
+ alphanumeric + underscore; avoid dots, since
+ ``traffic_ctl --directive my_plugin.dry_run=true`` parses the
+ first ``.`` as the directive separator.
+
+ **Plugins with multiple files:**
+
+ - If the files share the same logical config and should reload
+ together, register once and add the rest via
+ :func:`TSCfgAddFileDependency` (single task per reload).
+ - If the files are genuinely independent and reloadable on their
+ own, register each separately with a disambiguating key
+ (e.g. ``my_plugin_main``, ``my_plugin_aux``). Each becomes its
+ own task entry in :option:`traffic_ctl config status`.
+
+ Required.
+
+ .. var:: std::string_view config_path
+
+ Default config file path (absolute, or relative to ``sysconfdir``).
+ Required.
+
+ .. var:: std::string_view filename_record
+
+ Fully-qualified record name that holds the active config filename,
+ or ``{}`` (default) if the path is fixed. When set, the operator
+ can change the active config file at runtime by editing this
+ record; ``config_path`` is used as the fallback when the record is
+ empty or unset. Optional.
+
+ .. var:: TSCfgLoadCb handler
+
+ Reload callback invoked when the file changes, when an attached
+ trigger record changes, or when the operator triggers an RPC
+ reload. Required.
+
+ .. var:: void *data
+
+ Opaque pointer passed unmodified to ``handler`` on every invocation.
+ The plugin owns it; ATS does not copy or free it. Must outlive the
+ registration - typically a ``static`` or once-allocated heap object
+ stashed in ``TSPluginInit``::
+
+ static PluginState state;
+ state.config_path = ...;
+
+ TSCfgRegistrationInfo info{};
+ info.handler = config_reload;
+ info.data = &state;
+ TSCfgRegister(&info);
+
+ .. var:: TSCfgSourceType source
+
+ Whether ``handler`` can also process YAML content supplied via RPC.
+ Defaults to :enumerator:`TSCfgSourceType::TS_CFG_SOURCE_FILE_ONLY`.
+
+ .. var:: bool is_required
+
+ Hint propagated to FileManager: marks the file as "required" in
+ catalog/inspection output and emits a ``Dbg`` line if the file
+ is missing at registration time. The framework does **not**
+ enforce this flag at reload-time today: the handler is still
+ invoked even when the file is missing or invalid, and the
+ plugin chooses whether to fail the reload. Defaults to ``false``.
+
+.. type:: TSCfgFileDependencyInfo
+
+ Options struct passed to :func:`TSCfgAddFileDependency`. Only ``key``
+ and ``config_path`` are required.
+
+ .. var:: std::string_view key
+
+ Parent registry key as passed to :func:`TSCfgRegister`. Required.
+
+ .. var:: std::string_view config_path
+
+ Default companion file path (absolute, or relative to ``sysconfdir``).
+ Required.
+
+ .. var:: std::string_view filename_record
+
+ Fully-qualified record name that holds the filename, or ``{}`` if
+ the path is fixed. Optional.
+
+ .. var:: std::string_view dep_key
+
+ Routing key for inline YAML supplied via JSONRPC. When non-empty,
+ content delivered under this top-level node is routed to the parent
+ entry's handler, giving the plugin parity with core
+ composite-config patterns. When empty (default), the dependency is
+ file-change-only.
+
+ .. var:: bool is_required
+
+ Hint propagated to FileManager (catalog/inspection only); see the
+ equivalent field on :type:`TSCfgRegistrationInfo`. Defaults to
+ ``false``.
+
+.. type:: TSCfgLoadCtx
+
+ Opaque handle to a per-reload context. The context tracks the
+ lifecycle of a single reload attempt for one registered config: it
+ carries the reload token, supplied YAML (for RPC reloads), the
+ filename (for file reloads), and the task state machine the framework
+ uses to aggregate results.
+
+.. type:: void (*TSCfgLoadCb)(TSCfgLoadCtx ctx, void *data)
+
+ Plugin reload callback signature. ``data`` is the opaque pointer the
+ plugin supplied via :var:`TSCfgRegistrationInfo::data`.
+
+.. enum:: TSCfgLogLevel
+
+ Severity for log entries emitted via :func:`TSCfgLoadCtxAddLog`.
+
+ .. enumerator:: TS_CFG_LOG_NOTE
+
+ Informational. Default level. Maps to ``DL_Note`` internally.
+
+ .. enumerator:: TS_CFG_LOG_WARNING
+
+ Concerning; the reload may still complete. Maps to ``DL_Warning``.
+
+ .. enumerator:: TS_CFG_LOG_ERROR
+
+ Failure cause; pair with a subsequent :func:`TSCfgLoadCtxFail`.
+ Maps to ``DL_Error``.
+
+ The framework deliberately does not expose the fatal-class diagnostics
+ levels here: a reload handler should not be able to terminate the
+ process. Plugins that truly need debug-only output should use
+ ``Dbg(ctl, ...)`` instead of this API.
+
+.. function:: TSReturnCode TSCfgRegister(const TSCfgRegistrationInfo *info)
+.. function:: TSReturnCode TSCfgAttachReloadTrigger(std::string_view key, std::string_view record_name)
+.. function:: TSReturnCode TSCfgAddFileDependency(const TSCfgFileDependencyInfo *info)
+.. function:: void TSCfgLoadCtxInProgress(TSCfgLoadCtx ctx, std::string_view msg)
+.. function:: void TSCfgLoadCtxComplete(TSCfgLoadCtx ctx, std::string_view msg)
+.. function:: void TSCfgLoadCtxFail(TSCfgLoadCtx ctx, std::string_view msg)
+.. function:: void TSCfgLoadCtxAddLog(TSCfgLoadCtx ctx, TSCfgLogLevel level, std::string_view msg)
+.. function:: TSCfgLoadCtx TSCfgLoadCtxAddSubtask(TSCfgLoadCtx ctx, std::string_view description)
+.. function:: std::string_view TSCfgLoadCtxGetFilename(TSCfgLoadCtx ctx)
+.. function:: std::string_view TSCfgLoadCtxGetReloadToken(TSCfgLoadCtx ctx)
+.. function:: TSYaml TSCfgLoadCtxGetSuppliedYaml(TSCfgLoadCtx ctx)
+.. function:: TSYaml TSCfgLoadCtxGetReloadDirectives(TSCfgLoadCtx ctx)
+
+Description
+===========
+
+These functions are the plugin-facing entry points to the |TS|
+configuration reload framework. A plugin registers a config file
+together with a reload callback, and the framework drives the callback
+whenever the file changes, an attached trigger record changes, or an
+operator triggers a reload via JSONRPC.
+
+The plugin name (set via :func:`TSPluginRegister`) is automatically
+attached to every registered entry, so reload-trace logs and
+:option:`traffic_ctl config status` output identify which plugin owns
+which entry as ``[plugin: <name>]``. Plugins do not pass their name
+explicitly.
+
+Registration
+------------
+
+:func:`TSCfgRegister`
+ Registers a config file and reload handler.
+
+ Must be called from :func:`TSPluginInit`, **after**
+ :func:`TSPluginRegister`. Returns ``TS_ERROR`` if called outside
+ ``TSPluginInit``, before ``TSPluginRegister``, with a null or
+ incomplete ``info`` struct, or if another plugin (or core) has
+ already registered the same key.
Review Comment:
This documentation says TSCfgRegister returns TS_ERROR if another plugin/core has already registered the same key, but the implementation intentionally does not signal duplicate-key registration via the return value (it logs a Warning and still returns TS_SUCCESS once preconditions pass). Please reconcile the doc with the actual API behavior (or change the implementation to match the documented contract).
##########
tests/gold_tests/jsonrpc/config_reload_directives_plugin.test.py:
##########
@@ -0,0 +1,174 @@
+'''
+Test TSCfgLoadCtxGetReloadDirectives plugin API — verifies that _reload
+directives are correctly delivered to the plugin handler, separate from
+the supplied config YAML content.
+
+Test scenarios:
+ A. Plugin startup: register succeeds
+ B. RPC reload with _reload directives (version) + config content (greeting)
+ C. File-based reload (touch config) — no directives
+ D. RPC reload with empty _reload directives — no version key
+'''
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from jsonrpc import Request, Response
+
+Test.Summary = 'Test TSCfgLoadCtxGetReloadDirectives plugin API'
+Test.ContinueOnFail = True
+
+ts = Test.MakeATSProcess('ts', dump_runroot=True)
+
+Test.testName = 'config_reload_directives_plugin'
+
+ts.Disk.records_config.update(
+ {
+ 'proxy.config.diags.debug.enabled': 1,
+ 'proxy.config.diags.debug.tags': 'rpc|config|config.reload|cfg_plugin_directives_test',
+ })
+
+# Write initial valid plugin config file
+ts.Disk.MakeConfigFile('cfg_plugin_directives_test.conf').AddLines([
+ 'initial: config',
+])
+
+# Load the directives test plugin
+Test.PrepareTestPlugin(
+ os.path.join(Test.Variables.AtsBuildGoldTestsDir, 'jsonrpc', 'plugins', '.libs', 'cfg_plugin_directives_test.so'), ts,
+ 'cfg_plugin_directives_test.conf')
+
+# ============================================================================
+# Test A: Plugin startup — TSCfgRegister succeeds
+# ============================================================================
+tr = Test.AddTestRun("Plugin loads and registers")
+tr.Processes.Default.StartBefore(ts)
+tr.Processes.Default.Command = "sleep 2"
+tr.Processes.Default.ReturnCode = 0
+tr.StillRunningAfter = ts
+
+# Init-API confirmation is emitted via Dbg() under the cfg_plugin_directives_test tag,
+# so it lands in traffic.out, not diags.log.
+ts.Disk.traffic_out.Content = Testers.IncludesExpression('TSCfgRegister OK', 'TSCfgRegister should succeed')
+
+ts.Disk.diags_log.Content = All(
+ Testers.IncludesExpression(r'Config reload \[rpc-with-directives\] completed',
+ 'Reload with directives should appear in diags'),)
+
+# ============================================================================
+# Test B: RPC reload with _reload directives + config content
+# The framework extracts _reload into directives, remaining content becomes
+# supplied_yaml. Plugin should see both directive_version and content_greeting.
+# ============================================================================
+tr = Test.AddTestRun("RPC reload with _reload directives and config content")
+tr.AddJsonRPCClientRequest(
+ ts,
+ Request.admin_config_reload(
+ token='rpc-with-directives',
+ configs={'cfg_plugin_directives_test': {
+ 'greeting': 'hello_directives',
+ '_reload': {
+ 'version': '2.0'
+ }
+ }}))
+
+
+def validate_rpc_directives(resp: Response):
+ result = resp.result
+ errors = result.get('errors', [])
+ if errors:
+ return (False, f"Should accept RPC content: {errors}")
+ return (True, f"RPC with directives accepted: token={result.get('token', '')}")
+
+
+tr.Processes.Default.Streams.stdout = Testers.CustomJSONRPCResponse(validate_rpc_directives)
+tr.StillRunningAfter = ts
+
+tr = Test.AddTestRun("Verify directives and content in status")
+tr.DelayStart = 5
+tr.Processes.Default.Command = "traffic_ctl config status -t rpc-with-directives"
+tr.Processes.Default.Env = ts.Env
+tr.Processes.Default.ReturnCode = 0
+tr.Processes.Default.Streams.stdout = All(
+ Testers.IncludesExpression('directive_version=2.0', 'Plugin should see version directive'),
+ Testers.IncludesExpression('content_greeting=hello_directives', 'Plugin should see greeting in content'),
+ Testers.IncludesExpression('success', 'Should complete successfully'),
+ Testers.IncludesExpression('[plugin]', 'Should have plugin tag'),
Review Comment:
The test asserts `[plugin]` in output, but traffic_ctl prints `[plugin: <name>]` and (if these are regex-based matchers) `[plugin]` is interpreted as a character class. Update the matcher to escape brackets and/or match the `[plugin:` prefix so the assertion is meaningful.
##########
tests/gold_tests/jsonrpc/config_reload_plugin_api.test.py:
##########
@@ -0,0 +1,273 @@
+'''
+Test the TSCfg* plugin config API end-to-end.
+
+Registration APIs (called in TSPluginInit):
+ 1. TSCfgRegister — plugin loads and registers
+ 2. TSCfgAttachReloadTrigger — record change fires handler
+ 3. TSCfgAddFileDependency — companion file change fires handler
+
+Handler APIs (called during reload):
+ 4. TSCfgLoadCtxGetSuppliedYaml — RPC vs file detection
+ 5. TSCfgLoadCtxGetFilename — file path resolution
+ 6. TSCfgLoadCtxInProgress — in-progress marker (always called)
+ 7. TSCfgLoadCtxAddLog — intermediate log entries
+ 8. TSCfgLoadCtxComplete — success reporting
+ 9. TSCfgLoadCtxFail — failure reporting
+ 10. TSCfgLoadCtxAddSubtask — child subtask creation
+
+Test scenarios:
+ A. Plugin startup: register + attach trigger + add dependency
+ B. RPC reload — success with greeting
+ C. RPC reload — fail_on_purpose
+ D. RPC reload — with_subtask (parent + child both complete)
+ E. RPC reload — subtask_fail (child fails, parent completes)
+ F. Record-trigger reload (change proxy.config.http.insert_age_in_response)
+ G. Core tasks lack [plugin] tag
+'''
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from jsonrpc import Request, Response
+
+Test.Summary = 'Test TSCfg* plugin config API: all 10 functions'
+Test.ContinueOnFail = True
+
+ts = Test.MakeATSProcess('ts', dump_runroot=True)
+
+Test.testName = 'config_reload_plugin_api'
+
+ts.Disk.records_config.update(
+ {
+ 'proxy.config.diags.debug.enabled': 1,
+ 'proxy.config.diags.debug.tags': 'rpc|config|config.reload|cfg_plugin_test',
+ })
+
+# Write initial valid plugin config file
+plugin_config_file = os.path.join(ts.Variables.CONFIGDIR, 'cfg_plugin_test.conf')
+ts.Disk.MakeConfigFile('cfg_plugin_test.conf').AddLines([
+ 'greeting: hello',
+])
+
+# Write companion file for TSCfgAddFileDependency
+companion_file = os.path.join(ts.Variables.CONFIGDIR, 'cfg_plugin_companion.conf')
+ts.Disk.MakeConfigFile('cfg_plugin_companion.conf').AddLines([
+ 'companion: data',
+])
+
+# Load the test plugin with main config + companion file
+Test.PrepareTestPlugin(
+ os.path.join(Test.Variables.AtsBuildGoldTestsDir, 'jsonrpc', 'plugins', '.libs', 'cfg_plugin_test.so'), ts,
+ 'cfg_plugin_test.conf cfg_plugin_companion.conf')
+
+# ============================================================================
+# Test A: Plugin startup — TSCfgRegister + TSCfgAttachReloadTrigger + TSCfgAddFileDependency
+# ============================================================================
+tr = Test.AddTestRun("Plugin loads and registers all init APIs")
+tr.Processes.Default.StartBefore(ts)
+tr.Processes.Default.Command = "sleep 2"
+tr.Processes.Default.ReturnCode = 0
+tr.StillRunningAfter = ts
+
+# Init-API confirmations are emitted via Dbg() under the cfg_plugin_test tag,
+# so they land in traffic.out, not diags.log.
+ts.Disk.traffic_out.Content = All(
+ Testers.IncludesExpression('TSCfgRegister OK', 'TSCfgRegister should succeed'),
+ Testers.IncludesExpression('TSCfgAttachReloadTrigger OK', 'TSCfgAttachReloadTrigger should succeed'),
+ Testers.IncludesExpression('TSCfgAddFileDependency OK', 'TSCfgAddFileDependency should succeed'),
+)
+
+ts.Disk.diags_log.Content = All(
+ # Reload summaries should land in diags.log (escape brackets for regex)
+ Testers.IncludesExpression(r'Config reload \[rpc-greet\] completed', 'Reload summary for rpc-greet should appear in diags'),
+ Testers.IncludesExpression(
+ r'Config reload \[rpc-fail\] finished with failures', 'Reload summary for rpc-fail should report failure in diags'),
+ Testers.IncludesExpression(r'Config reload \[rpc-subtask\] completed', 'Reload summary for rpc-subtask should appear in diags'),
+ Testers.IncludesExpression(
+ r'Config reload \[rpc-subtask-fail\] finished with failures',
+ 'Reload summary for rpc-subtask-fail should report failure in diags'),
+ Testers.IncludesExpression(r'Config reload \[core-check\] completed', 'Reload summary for core-check should appear in diags'),
+ Testers.ExcludesExpression('ignoring transition from', 'No terminal state conflicts'),
+)
+
+# ============================================================================
+# Test B: RPC reload — greet (exercises GetSuppliedYaml, InProgress, AddLog, Complete)
+# ============================================================================
+tr = Test.AddTestRun("RPC reload with greet key")
+tr.AddJsonRPCClientRequest(ts, Request.admin_config_reload(token='rpc-greet', configs={'cfg_plugin_test': {'greet': 'world'}}))
+
+
+def validate_rpc_greet(resp: Response):
+ result = resp.result
+ errors = result.get('errors', [])
+ if errors:
+ return (False, f"Should accept RPC content: {errors}")
+ return (True, f"RPC greet accepted: token={result.get('token', '')}")
+
+
+tr.Processes.Default.Streams.stdout = Testers.CustomJSONRPCResponse(validate_rpc_greet)
+tr.StillRunningAfter = ts
+
+tr = Test.AddTestRun("Verify greet reload status")
+tr.DelayStart = 5
+tr.Processes.Default.Command = "traffic_ctl config status -t rpc-greet"
+tr.Processes.Default.Env = ts.Env
+tr.Processes.Default.ReturnCode = 0
+tr.Processes.Default.Streams.stdout = All(
+ Testers.IncludesExpression('[plugin]', 'Plugin task should have [plugin] tag'),
+ Testers.IncludesExpression('greet=world', 'Should show greeting in status'),
+ Testers.IncludesExpression('success', 'Should show success'),
+ Testers.IncludesExpression('handler entered', 'TSCfgLoadCtxAddLog message should appear'),
+)
Review Comment:
The status output now tags plugin-owned tasks as `[plugin: <name>]`. These assertions use the regex pattern `[plugin]`, which (if treated as a regex) is a character class and won’t match the literal bracketed tag. Consider matching/escaping the literal brackets (e.g. `\[plugin:`) so the test reliably validates plugin attribution.
##########
tests/gold_tests/jsonrpc/config_reload_plugin_api.test.py:
##########
@@ -0,0 +1,273 @@
+'''
+Test the TSCfg* plugin config API end-to-end.
+
+Registration APIs (called in TSPluginInit):
+ 1. TSCfgRegister — plugin loads and registers
+ 2. TSCfgAttachReloadTrigger — record change fires handler
+ 3. TSCfgAddFileDependency — companion file change fires handler
+
+Handler APIs (called during reload):
+ 4. TSCfgLoadCtxGetSuppliedYaml — RPC vs file detection
+ 5. TSCfgLoadCtxGetFilename — file path resolution
+ 6. TSCfgLoadCtxInProgress — in-progress marker (always called)
+ 7. TSCfgLoadCtxAddLog — intermediate log entries
+ 8. TSCfgLoadCtxComplete — success reporting
+ 9. TSCfgLoadCtxFail — failure reporting
+ 10. TSCfgLoadCtxAddSubtask — child subtask creation
+
+Test scenarios:
+ A. Plugin startup: register + attach trigger + add dependency
+ B. RPC reload — success with greeting
+ C. RPC reload — fail_on_purpose
+ D. RPC reload — with_subtask (parent + child both complete)
+ E. RPC reload — subtask_fail (child fails, parent completes)
+ F. Record-trigger reload (change proxy.config.http.insert_age_in_response)
+ G. Core tasks lack [plugin] tag
+'''
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from jsonrpc import Request, Response
+
+Test.Summary = 'Test TSCfg* plugin config API: all 10 functions'
+Test.ContinueOnFail = True
+
+ts = Test.MakeATSProcess('ts', dump_runroot=True)
+
+Test.testName = 'config_reload_plugin_api'
+
+ts.Disk.records_config.update(
+ {
+ 'proxy.config.diags.debug.enabled': 1,
+ 'proxy.config.diags.debug.tags': 'rpc|config|config.reload|cfg_plugin_test',
+ })
+
+# Write initial valid plugin config file
+plugin_config_file = os.path.join(ts.Variables.CONFIGDIR, 'cfg_plugin_test.conf')
+ts.Disk.MakeConfigFile('cfg_plugin_test.conf').AddLines([
+ 'greeting: hello',
+])
+
+# Write companion file for TSCfgAddFileDependency
+companion_file = os.path.join(ts.Variables.CONFIGDIR, 'cfg_plugin_companion.conf')
+ts.Disk.MakeConfigFile('cfg_plugin_companion.conf').AddLines([
+ 'companion: data',
+])
+
+# Load the test plugin with main config + companion file
+Test.PrepareTestPlugin(
+ os.path.join(Test.Variables.AtsBuildGoldTestsDir, 'jsonrpc', 'plugins', '.libs', 'cfg_plugin_test.so'), ts,
+ 'cfg_plugin_test.conf cfg_plugin_companion.conf')
+
+# ============================================================================
+# Test A: Plugin startup — TSCfgRegister + TSCfgAttachReloadTrigger + TSCfgAddFileDependency
+# ============================================================================
+tr = Test.AddTestRun("Plugin loads and registers all init APIs")
+tr.Processes.Default.StartBefore(ts)
+tr.Processes.Default.Command = "sleep 2"
+tr.Processes.Default.ReturnCode = 0
+tr.StillRunningAfter = ts
+
+# Init-API confirmations are emitted via Dbg() under the cfg_plugin_test tag,
+# so they land in traffic.out, not diags.log.
+ts.Disk.traffic_out.Content = All(
+ Testers.IncludesExpression('TSCfgRegister OK', 'TSCfgRegister should succeed'),
+ Testers.IncludesExpression('TSCfgAttachReloadTrigger OK', 'TSCfgAttachReloadTrigger should succeed'),
+ Testers.IncludesExpression('TSCfgAddFileDependency OK', 'TSCfgAddFileDependency should succeed'),
+)
+
+ts.Disk.diags_log.Content = All(
+ # Reload summaries should land in diags.log (escape brackets for regex)
+ Testers.IncludesExpression(r'Config reload \[rpc-greet\] completed', 'Reload summary for rpc-greet should appear in diags'),
+ Testers.IncludesExpression(
+ r'Config reload \[rpc-fail\] finished with failures', 'Reload summary for rpc-fail should report failure in diags'),
+ Testers.IncludesExpression(r'Config reload \[rpc-subtask\] completed', 'Reload summary for rpc-subtask should appear in diags'),
+ Testers.IncludesExpression(
+ r'Config reload \[rpc-subtask-fail\] finished with failures',
+ 'Reload summary for rpc-subtask-fail should report failure in diags'),
+ Testers.IncludesExpression(r'Config reload \[core-check\] completed', 'Reload summary for core-check should appear in diags'),
+ Testers.ExcludesExpression('ignoring transition from', 'No terminal state conflicts'),
+)
+
+# ============================================================================
+# Test B: RPC reload — greet (exercises GetSuppliedYaml, InProgress, AddLog, Complete)
+# ============================================================================
+tr = Test.AddTestRun("RPC reload with greet key")
+tr.AddJsonRPCClientRequest(ts, Request.admin_config_reload(token='rpc-greet', configs={'cfg_plugin_test': {'greet': 'world'}}))
+
+
+def validate_rpc_greet(resp: Response):
+ result = resp.result
+ errors = result.get('errors', [])
+ if errors:
+ return (False, f"Should accept RPC content: {errors}")
+ return (True, f"RPC greet accepted: token={result.get('token', '')}")
+
+
+tr.Processes.Default.Streams.stdout = Testers.CustomJSONRPCResponse(validate_rpc_greet)
+tr.StillRunningAfter = ts
+
+tr = Test.AddTestRun("Verify greet reload status")
+tr.DelayStart = 5
+tr.Processes.Default.Command = "traffic_ctl config status -t rpc-greet"
+tr.Processes.Default.Env = ts.Env
+tr.Processes.Default.ReturnCode = 0
+tr.Processes.Default.Streams.stdout = All(
+ Testers.IncludesExpression('[plugin]', 'Plugin task should have [plugin] tag'),
+ Testers.IncludesExpression('greet=world', 'Should show greeting in status'),
+ Testers.IncludesExpression('success', 'Should show success'),
+ Testers.IncludesExpression('handler entered', 'TSCfgLoadCtxAddLog message should appear'),
+)
+tr.StillRunningAfter = ts
+
+# ============================================================================
+# Test C: RPC reload — fail_on_purpose (exercises Fail + AddLog)
+# ============================================================================
+tr = Test.AddTestRun("RPC reload with fail_on_purpose")
+tr.DelayStart = 2
+tr.AddJsonRPCClientRequest(
+ ts, Request.admin_config_reload(token='rpc-fail', configs={'cfg_plugin_test': {
+ 'fail_on_purpose': True
+ }}, force=True))
+
+
+def validate_rpc_fail(resp: Response):
+ result = resp.result
+ errors = result.get('errors', [])
+ if errors:
+ error_str = str(errors)
+ if '6011' in error_str or '6010' in error_str:
+ return (False, f"Plugin should accept RPC content: {errors}")
+ return (True, f"RPC fail dispatched: token={result.get('token', '')}")
+
+
+tr.Processes.Default.Streams.stdout = Testers.CustomJSONRPCResponse(validate_rpc_fail)
+tr.StillRunningAfter = ts
+
+tr = Test.AddTestRun("Verify fail reload status")
+tr.DelayStart = 5
+tr.Processes.Default.Command = "traffic_ctl config status -t rpc-fail"
+tr.Processes.Default.Env = ts.Env
+tr.Processes.Default.ReturnCode = 0
+tr.Processes.Default.Streams.stdout = All(
+ Testers.IncludesExpression('[plugin]', 'Failed task should have [plugin] tag'),
Review Comment:
Same issue as above: `[plugin]` is not a safe regex to assert the plugin attribution tag (and doesn’t match the new `[plugin: <name>]` format). Escape the brackets / match the prefix so this verifies the intended output.
##########
plugins/regex_revalidate/regex_revalidate.cc:
##########
@@ -587,19 +578,43 @@ config_handler(TSCont cont, TSEvent event, void * /* edata ATS_UNUSED */)
TSContDataSet(free_cont, (void *)iptr);
TSContScheduleOnPool(free_cont, FREE_TMOUT, TS_THREAD_POOL_TASK);
}
- } else {
- Dbg(dbg_ctl, "No Changes");
- if (i) {
- free_invalidate_t_list(i);
- }
+ return true;
}
+ Dbg(dbg_ctl, "No Changes");
+ if (i) {
+ free_invalidate_t_list(i);
+ }
+ return false;
+}
+
+static void
+config_reload(TSCfgLoadCtx ctx, void *data)
+{
+ auto *pstate = static_cast<plugin_state_t *>(data);
+
+ Dbg(dbg_ctl, "Config reload via ConfigRegistry");
+ bool const updated = do_config_reload(pstate);
+ TSCfgLoadCtxComplete(ctx, updated ? "regex_revalidate config reloaded" : "regex_revalidate config unchanged");
+}
Review Comment:
regex_revalidate now participates in the reload framework via config_reload(), but do_config_reload() is called there without any synchronization. The timed reload path still locks the continuation mutex around do_config_reload(), so a timed reload and a framework-triggered reload can run concurrently and race/free the invalidate list. Consider adding a shared mutex in plugin_state_t (or otherwise reusing the same lock) and taking it in both config_handler() and config_reload().
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#discussion_r3302724393
##########
src/api/InkAPI.cc:
##########
@@ -3299,6 +3302,347 @@ TSMgmtUpdateRegister(TSCont contp, const char *plugin_name, const char *plugin_f
global_config_cbs->insert(reinterpret_cast<INKContInternal *>(contp), plugin_name, plugin_file_name);
}
+////////////////////////////////////////////////////////////////////
+//
+// Config Registry - plugin config reload registration
+//
+////////////////////////////////////////////////////////////////////
+
+namespace
+{
+// Handle behind the opaque TSCfgLoadCtx. The wrapper lambda new's one per
+// handler invocation; TSCfgLoadCtx{Complete,Fail} delete it. Caches the
+// strings/nodes the getters need to return as stable pointers.
+struct PluginConfigContext {
+ ConfigContext ctx;
+ std::string filename;
+ std::string reload_token;
+ YAML::Node supplied_yaml;
+ YAML::Node reload_directives;
+ std::atomic<bool> consumed{false};
+};
+
+DbgCtl dbg_ctl_plugin_config{"config.reload"};
+
+/// Verify we're inside TSPluginInit() after a successful TSPluginRegister().
+/// Returns the active plugin name on success, nullptr on failure (after logging).
+const char *
+validate_plugin_init(const char *api_fn)
+{
+ if (!plugin_reg_current) {
+ Error("[unknown-plugin] %s must be called from TSPluginInit()", api_fn);
+ return nullptr;
+ }
+ if (!plugin_reg_current->plugin_registered || plugin_reg_current->plugin_name == nullptr) {
+ Error("[%s] %s must be called after TSPluginRegister() with a non-null plugin_name",
+ plugin_reg_current->plugin_path ? plugin_reg_current->plugin_path : "?", api_fn);
+ return nullptr;
+ }
+ return plugin_reg_current->plugin_name;
+}
+} // anonymous namespace
+
+TSReturnCode
+TSCfgRegister(const TSCfgRegistrationInfo *info)
+{
+ const char *plugin_name = validate_plugin_init("TSCfgRegister");
+ if (!plugin_name) {
+ return TS_ERROR;
+ }
+
+ if (info == nullptr) {
+ Error("[%s] TSCfgRegister: info is null", plugin_name);
+ return TS_ERROR;
+ }
+ if (info->key.empty() || info->config_path.empty() || info->handler == nullptr) {
+ Error("[%s] TSCfgRegister: missing required fields (key/config_path/handler)", plugin_name);
+ return TS_ERROR;
+ }
+
+ std::string key_str{info->key};
+ std::string config_path_str{info->config_path};
+ std::string filename_record_str{info->filename_record};
+
+ config::ConfigSource cfg_source =
+ (info->source == TS_CFG_SOURCE_FILE_AND_RPC) ? config::ConfigSource::FileAndRpc : config::ConfigSource::FileOnly;
+
+ auto cb = info->handler;
+ auto udata = info->data;
+
+ // Lambda captures only the function pointer + opaque user data. Plugin name
+ // and key live on the Entry; the wrapper looks them up via the ctx that the
+ // framework attaches them to (set_plugin_name in ConfigRegistry).
+ config::ConfigReloadHandler wrapper = [cb, udata](ConfigContext ctx) {
+ auto *handle = new PluginConfigContext{};
+ handle->reload_token = ctx.get_reload_token();
+ handle->supplied_yaml = ctx.supplied_yaml();
+ handle->reload_directives = ctx.reload_directives();
+ auto const &key = ctx.get_description();
+ if (auto const *entry = config::ConfigRegistry::Get_Instance().find(key); entry != nullptr) {
+ handle->filename = entry->resolve_filename();
+ }
+ handle->ctx = std::move(ctx);
+
+ Dbg(dbg_ctl_plugin_config, "Invoking plugin config handler for '%s'", key.c_str());
+ cb(reinterpret_cast<TSCfgLoadCtx>(handle), udata);
+ // Past this point @p handle may be deleted (synchronous completion). Deferred
+ // completion is detected upstream via ctx.is_terminal(). If the plugin never
+ // completes, the handle leaks but core's progress timeout still unblocks.
+ };
+
+ // Duplicate-key handling lives in ConfigRegistry::do_register and emits a
+ // Warning identifying both owners; callers can probe with TSCfgIsRegistered.
+ config::ConfigRegistry::Get_Instance().register_plugin_config(key_str, plugin_name, config_path_str, filename_record_str,
+ std::move(wrapper), cfg_source, {}, info->is_required);
+
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgRegister: registered '%s' (file: %s)", plugin_name, key_str.c_str(),
+ config_path_str.c_str());
+ return TS_SUCCESS;
+}
+
+bool
+TSCfgIsRegistered(std::string_view key)
+{
+ if (key.empty()) {
+ return false;
+ }
+ return config::ConfigRegistry::Get_Instance().contains(std::string{key});
+}
+
+TSReturnCode
+TSCfgAttachReloadTrigger(std::string_view key, std::string_view record_name)
+{
+ const char *plugin_name = validate_plugin_init("TSCfgAttachReloadTrigger");
+ if (!plugin_name) {
+ return TS_ERROR;
+ }
+ if (key.empty() || record_name.empty()) {
+ Error("[%s] TSCfgAttachReloadTrigger: key and record_name required", plugin_name);
+ return TS_ERROR;
+ }
+
+ std::string key_str{key};
+ std::string record_str{record_name};
+ if (config::ConfigRegistry::Get_Instance().attach(key_str, record_str.c_str()) != 0) {
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgAttachReloadTrigger: key '%s' not found", plugin_name, key_str.c_str());
+ return TS_ERROR;
+ }
+
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgAttachReloadTrigger: attached record '%s' to config '%s'", plugin_name, record_str.c_str(),
+ key_str.c_str());
+ return TS_SUCCESS;
+}
+
+TSReturnCode
+TSCfgAddFileDependency(const TSCfgFileDependencyInfo *info)
+{
+ const char *plugin_name = validate_plugin_init("TSCfgAddFileDependency");
+ if (!plugin_name) {
+ return TS_ERROR;
+ }
+ if (info == nullptr) {
+ Error("[%s] TSCfgAddFileDependency: info is null", plugin_name);
+ return TS_ERROR;
+ }
+ if (info->key.empty() || info->config_path.empty()) {
+ Error("[%s] TSCfgAddFileDependency: missing required fields (key/config_path)", plugin_name);
+ return TS_ERROR;
+ }
+
+ auto ®istry = config::ConfigRegistry::Get_Instance();
+ std::string key_str = std::string{info->key};
+ std::string path_str = std::string{info->config_path};
+ std::string filename_record_str = std::string{info->filename_record};
+ std::string dep_key_str = std::string{info->dep_key};
+ bool const has_dep_key = !dep_key_str.empty();
+
+ // filename_record_str may be empty; add_file_dependency / resolve_config_filename treat empty as "no record".
+ const char *filename_record_arg = filename_record_str.empty() ? nullptr : filename_record_str.c_str();
+
+ int rc = has_dep_key ?
+ registry.add_file_and_node_dependency(key_str, dep_key_str, filename_record_arg, path_str.c_str(), info->is_required) :
+ registry.add_file_dependency(key_str, filename_record_arg, path_str.c_str(), info->is_required);
+
+ if (rc != 0) {
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgAddFileDependency: key '%s' not found", plugin_name, key_str.c_str());
Review Comment:
TSCfgAddFileDependency logs "key '%s' not found" whenever the registry call returns non-zero, but add_file_dependency/add_file_and_node_dependency can also fail for reasons other than an unknown key (e.g., dep_key collisions, record-callback wiring failures). Please adjust the diagnostic so it doesn’t misreport the failure cause (include key/dep_key/filename_record and avoid claiming the key is missing unless verified).
##########
src/mgmt/config/ConfigRegistry.cc:
##########
@@ -333,40 +377,54 @@ ConfigRegistry::add_file_dependency(const std::string &key, const char *filename
config_key = it->second.key;
}
- auto resolved = resolve_config_filename(filename_record, default_filename);
+ bool has_record = (filename_record != nullptr && filename_record[0] != '\0');
+ auto resolved = resolve_config_filename(has_record ? filename_record : nullptr, default_filename);
- Dbg(dbg_ctl, "Adding file dependency '%s' (resolved: %s) to config '%s'", filename_record, resolved.c_str(), key.c_str());
+ Dbg(dbg_ctl, "Adding file dependency '%s' (resolved: %s) to config '%s'", has_record ? filename_record : "<none>",
+ resolved.c_str(), key.c_str());
// Register with FileManager for mtime-based change detection.
- // When rereadConfig() detects the file changed, it calls RecSetSyncRequired()
- // on the filename_record, which triggers on_record_change below.
- FileManager::instance().addFile(resolved.c_str(), filename_record, false, is_required);
+ // When filename_record is empty (e.g. plugin configs), pass the config key
+ // as the configName so process_config_update routes mtime changes back to
+ // ConfigRegistry::schedule_reload().
+ const char *config_name = has_record ? filename_record : config_key.c_str();
+ FileManager::instance().addFile(resolved.c_str(), config_name, false, is_required);
+
+ if (has_record) {
+ return wire_record_callback(filename_record, config_key);
+ }
Review Comment:
ConfigRegistry::add_file_dependency registers the file with FileManager before attempting wire_record_callback() when filename_record is set. If callback wiring fails, FileManager will still watch the file even though changes won’t trigger the registry handler. Consider wiring the record callback first (or rolling back the FileManager registration on failure) to avoid leaving partial state after an error.
##########
src/api/InkAPI.cc:
##########
@@ -3299,6 +3302,347 @@ TSMgmtUpdateRegister(TSCont contp, const char *plugin_name, const char *plugin_f
global_config_cbs->insert(reinterpret_cast<INKContInternal *>(contp), plugin_name, plugin_file_name);
}
+////////////////////////////////////////////////////////////////////
+//
+// Config Registry - plugin config reload registration
+//
+////////////////////////////////////////////////////////////////////
+
+namespace
+{
+// Handle behind the opaque TSCfgLoadCtx. The wrapper lambda new's one per
+// handler invocation; TSCfgLoadCtx{Complete,Fail} delete it. Caches the
+// strings/nodes the getters need to return as stable pointers.
+struct PluginConfigContext {
+ ConfigContext ctx;
+ std::string filename;
+ std::string reload_token;
+ YAML::Node supplied_yaml;
+ YAML::Node reload_directives;
+ std::atomic<bool> consumed{false};
+};
+
+DbgCtl dbg_ctl_plugin_config{"config.reload"};
+
+/// Verify we're inside TSPluginInit() after a successful TSPluginRegister().
+/// Returns the active plugin name on success, nullptr on failure (after logging).
+const char *
+validate_plugin_init(const char *api_fn)
+{
+ if (!plugin_reg_current) {
+ Error("[unknown-plugin] %s must be called from TSPluginInit()", api_fn);
+ return nullptr;
+ }
+ if (!plugin_reg_current->plugin_registered || plugin_reg_current->plugin_name == nullptr) {
+ Error("[%s] %s must be called after TSPluginRegister() with a non-null plugin_name",
+ plugin_reg_current->plugin_path ? plugin_reg_current->plugin_path : "?", api_fn);
+ return nullptr;
+ }
+ return plugin_reg_current->plugin_name;
+}
+} // anonymous namespace
+
+TSReturnCode
+TSCfgRegister(const TSCfgRegistrationInfo *info)
+{
+ const char *plugin_name = validate_plugin_init("TSCfgRegister");
+ if (!plugin_name) {
+ return TS_ERROR;
+ }
+
+ if (info == nullptr) {
+ Error("[%s] TSCfgRegister: info is null", plugin_name);
+ return TS_ERROR;
+ }
+ if (info->key.empty() || info->config_path.empty() || info->handler == nullptr) {
+ Error("[%s] TSCfgRegister: missing required fields (key/config_path/handler)", plugin_name);
+ return TS_ERROR;
+ }
+
+ std::string key_str{info->key};
+ std::string config_path_str{info->config_path};
+ std::string filename_record_str{info->filename_record};
+
+ config::ConfigSource cfg_source =
+ (info->source == TS_CFG_SOURCE_FILE_AND_RPC) ? config::ConfigSource::FileAndRpc : config::ConfigSource::FileOnly;
+
+ auto cb = info->handler;
+ auto udata = info->data;
+
+ // Lambda captures only the function pointer + opaque user data. Plugin name
+ // and key live on the Entry; the wrapper looks them up via the ctx that the
+ // framework attaches them to (set_plugin_name in ConfigRegistry).
+ config::ConfigReloadHandler wrapper = [cb, udata](ConfigContext ctx) {
+ auto *handle = new PluginConfigContext{};
+ handle->reload_token = ctx.get_reload_token();
+ handle->supplied_yaml = ctx.supplied_yaml();
+ handle->reload_directives = ctx.reload_directives();
+ auto const &key = ctx.get_description();
+ if (auto const *entry = config::ConfigRegistry::Get_Instance().find(key); entry != nullptr) {
+ handle->filename = entry->resolve_filename();
+ }
+ handle->ctx = std::move(ctx);
+
+ Dbg(dbg_ctl_plugin_config, "Invoking plugin config handler for '%s'", key.c_str());
+ cb(reinterpret_cast<TSCfgLoadCtx>(handle), udata);
+ // Past this point @p handle may be deleted (synchronous completion). Deferred
+ // completion is detected upstream via ctx.is_terminal(). If the plugin never
+ // completes, the handle leaks but core's progress timeout still unblocks.
+ };
+
+ // Duplicate-key handling lives in ConfigRegistry::do_register and emits a
+ // Warning identifying both owners; callers can probe with TSCfgIsRegistered.
+ config::ConfigRegistry::Get_Instance().register_plugin_config(key_str, plugin_name, config_path_str, filename_record_str,
+ std::move(wrapper), cfg_source, {}, info->is_required);
+
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgRegister: registered '%s' (file: %s)", plugin_name, key_str.c_str(),
+ config_path_str.c_str());
+ return TS_SUCCESS;
+}
+
+bool
+TSCfgIsRegistered(std::string_view key)
+{
+ if (key.empty()) {
+ return false;
+ }
+ return config::ConfigRegistry::Get_Instance().contains(std::string{key});
+}
+
+TSReturnCode
+TSCfgAttachReloadTrigger(std::string_view key, std::string_view record_name)
+{
+ const char *plugin_name = validate_plugin_init("TSCfgAttachReloadTrigger");
+ if (!plugin_name) {
+ return TS_ERROR;
+ }
+ if (key.empty() || record_name.empty()) {
+ Error("[%s] TSCfgAttachReloadTrigger: key and record_name required", plugin_name);
+ return TS_ERROR;
+ }
+
+ std::string key_str{key};
+ std::string record_str{record_name};
+ if (config::ConfigRegistry::Get_Instance().attach(key_str, record_str.c_str()) != 0) {
+ Dbg(dbg_ctl_plugin_config, "[%s] TSCfgAttachReloadTrigger: key '%s' not found", plugin_name, key_str.c_str());
Review Comment:
TSCfgAttachReloadTrigger logs "key '%s' not found" for any non-zero return from ConfigRegistry::attach(), but attach() can also fail when RecRegisterConfigUpdateCb wiring fails for the record. Consider logging a more accurate message (e.g., include both key and record_name, and avoid implying the key is missing unless that was the cause).
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#issuecomment-4544235003
> What happens when a plugin is unloaded or reinitialized? I couldn't find where the config context is unregistered when a plugin is unloaded.
This is only for global plugins, IIRC we do not unload/reinitialize global plugins. (unless we have a new feature that I am not aware of).
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#issuecomment-4729573063
@cmcfarlen ping. 😄
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 merged PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [TS API] Add plugin API for config reload framework [trafficserver]
Posted by "brbzull0 (via GitHub)" <gi...@apache.org>.
brbzull0 commented on PR #13146:
URL: https://github.com/apache/trafficserver/pull/13146#issuecomment-5216727410
[approve ci autest 2]
--
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: github-unsubscribe@trafficserver.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org