Review of the plugin-settings reconcile PRD (F1-F8) returned REVISE: the doc stated outcomes without making the decisions behind them. This revision makes each one, so the PRD can carry the plugin live-reload work: - ApplyMode is set to live and the gateway's version lag moves from the restart banner to the per-process applied-version rows. - The skills_dir refusal gets a check site (a pre-layer comparison on the live path, not the value-agnostic validator), keeping #1143's validates-nothing intact. - Records the four-directory coupling and why a whole-document refusal is acceptable. - Justifies stop-then-start as a module's only check, and adds the refused dependent-replace outcome to the apply-status taxonomy. - States that a reconcile tick re-runs layering and provider resolution, and what archie-gateway actually boots. - Adds the Verification section. Cited package paths re-checked against the tree; the control-plane definitions now cite internal/app/controlplane/.
135 lines
7.3 KiB
Markdown
135 lines
7.3 KiB
Markdown
# Plugin settings reconcile live
|
|
|
|
**Status:** Draft
|
|
**Revision:** 2
|
|
**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)
|
|
**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how
|
|
its changes take effect; `docs/architecture/plugins-and-extensions.md` owns the
|
|
plugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply
|
|
reports go.
|
|
|
|
## Outcome
|
|
|
|
An operator drops a plugin, module or secret-engine file into a configured
|
|
directory while archied runs, and the daemon loads it without a restart. An
|
|
edit to an installed file replaces what is running. A delete never stops running
|
|
code; apply status says so. A stored `plugin-settings` change applies live for
|
|
`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is
|
|
refused.
|
|
|
|
## Triggers
|
|
|
|
`PluginSettingsKind` joins `runtimeResourceKinds` in
|
|
`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes
|
|
`live` in `internal/app/controlplane/operational_settings.go`.
|
|
|
|
A poller reconciles on the apply-status restamp interval, so a dropped file
|
|
loads without a filesystem watch. Each tick re-runs both halves the boot path
|
|
runs, against the directories in the running config: the directory loads
|
|
(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the
|
|
layering (`boot.runtimeConfig`), which re-resolves provider credentials. A
|
|
provider disabled at boot for an unresolvable engine is re-resolved on the first
|
|
tick that finds it; a changed directory retargets the next tick without a
|
|
restart.
|
|
|
|
## Rules
|
|
|
|
- Adding and changing load; removing never unloads. Yaegi interpreters are not
|
|
reclaimed while a caller still exists and there is no unload path; the running
|
|
set can only grow. A removal stays outstanding in the apply-status error until
|
|
the process restarts.
|
|
- Each file is loaded through a fresh interpreter (the boot pattern) and
|
|
content-hashed, so only new and changed files load.
|
|
- A file that fails to load is skipped and reported; already-running code keeps
|
|
running, the degrade-and-skip convention `plugin.LoadDir` and
|
|
`Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule
|
|
for the module directory; a broken file at runtime skips without aborting.
|
|
- A directory that does not exist reconciles to an empty set.
|
|
|
|
## The three registries
|
|
|
|
- **Secret engines** (`internal/secret`). Reconciliation re-runs
|
|
`Registry.LoadDir` against the live directory. `Register` replaces by name, so
|
|
an edited engine takes effect for the next resolution and a dropped engine
|
|
resolves on the next tick. A deleted engine stays registered: existing
|
|
references keep resolving through it until restart. Engines are stateless
|
|
resolvers, so a swap needs no lifecycle step.
|
|
- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs
|
|
`ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves
|
|
through the registry at invoke time, so the swap reaches a running playbook
|
|
store unchanged; a deleted file leaves the old invoker in place, running.
|
|
- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside
|
|
`Register`, `Start` and `Stop`, and `Register` keeps its rule that
|
|
registration is allowed only before the first `Start`, so these are new host
|
|
methods rather than a relaxed `Register`. One adds a single module while the
|
|
host is running: inserted in dependency order, started alone, and rolled back
|
|
alone on failure, leaving every previously started module running. The other
|
|
replaces a module whose manifest id matches: stop it, start the new one, and
|
|
restart the old one when the new start fails; replacing a module another
|
|
running module depends on is refused. A module's `Start` is its only check
|
|
(`plugin.Module` has no probe, and one manifest id cannot be registered
|
|
twice), so a replacement checks by starting and keeps a rollback rather than
|
|
switching first. These operations obey the plugin engine rule: the host
|
|
invokes start and stop itself and isolates the failure to one module. A
|
|
deleted file makes no host call: the module runs on.
|
|
|
|
## `skills_dir`
|
|
|
|
`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`
|
|
document whose `skills_dir` differs from the value in force. The check is a
|
|
pre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in
|
|
`internal/app/archied/control_plane.go`), not an addition to
|
|
`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,
|
|
which stays value-agnostic per the #1143 decision recorded there: a
|
|
change-immutability rule needs the running config, and #1143's validates-nothing
|
|
still holds for values. The write lands, the store keeps the version, the daemon
|
|
publishes nothing, the refusal is reported against that stored version, and
|
|
last-known-good keeps running.
|
|
|
|
The layering assigns all four directories from one document, so a refused
|
|
`skills_dir` refuses the whole document and the other kinds still layer. That is
|
|
acceptable: `skills_dir` is the one field with no live consumer, a
|
|
whole-document refusal is the honest signal that none of it took effect, and an
|
|
operator changing `skills_dir` alongside another directory writes the two
|
|
changes separately.
|
|
|
|
## Apply status
|
|
|
|
One record per process: `archied` on `plugin-settings`, reported against the
|
|
version the process is running. The record's error field carries the outstanding
|
|
problem: a deleted file still running, a file that failed to load, the directory
|
|
failing to read, or a refused replace of a module another running module depends
|
|
on. A clean reconciliation clears the error. An add that succeeded is live even
|
|
while a removal is outstanding, and the error says so rather than showing the
|
|
kind as restart-required.
|
|
|
|
`ApplyMode` becomes `live`, so `RestartPendingBanner` no longer names
|
|
`plugin-settings`. The gateway's lag is shown instead by the per-process
|
|
applied-version rows on the Plugins page, which read the state
|
|
`applyStatusForKind` derives from `applied_version < storedVersion` in
|
|
`ui/src/stores/control-plane.ts`; that derivation is independent of
|
|
`ApplyMode`.
|
|
|
|
`archie-gateway` layers the `plugin-settings` document at boot through
|
|
`boot.loadRuntimeConfig` and reports it, but never calls `boot.loadPlugins` or
|
|
`boot.loadModules` and never reads the four directories, so it loads no plugin,
|
|
module or secret engine. With no live watch its row lags the stored version
|
|
until restart; that lag is a reporting lag, not a behaviour gap.
|
|
|
|
## Verification
|
|
|
|
- A plugin, module and secret-engine file dropped while the daemon runs loads on
|
|
the next tick; an unchanged file is not reloaded.
|
|
- An edited file replaces the running interpretation; a deleted file leaves the
|
|
running code running, with the process's error naming it until restart.
|
|
- A `skills_dir` change refuses the document: the store keeps the version, the
|
|
record carries that version and the refusal, and the running `skills_dir` is
|
|
unchanged.
|
|
- A plugin replacement whose new `Start` fails restarts the old module and
|
|
reports the failure; a replacement of a depended-on module is refused and the
|
|
dependent keeps running.
|
|
- A provider disabled at boot for a missing engine resolves again after the
|
|
engine file loads and a tick re-layers.
|
|
- The gateway reports the last version it layered at boot, loads no directory,
|
|
and its lag appears in its applied-version row rather than the restart banner.
|