Repository navigation
Description
Problem
"The plugins directory" is resolved independently in at least six places, and no two of them have to agree:
| Where | Resolves to |
|---|---|
Broker.App/Program.cs:68 |
Surgewave:PluginsDirectory ?? AppContext.BaseDirectory/plugins |
Tool — plugins install/list |
plugins, relative to the current working directory |
Tool — --install-dir (connectors) |
~/.surgewave/connectors |
Control/Program.cs:222 |
the literal "plugins" |
Connect.Worker/Program.cs:39 |
its own three-tier lookup |
Marketplace |
MarketplaceSignerOptions.PluginsDirectory = "plugins" |
#157 is one symptom: installing reports success, plugins list confirms it, and the broker never sees the plugin because it reads a different directory of the same name.
Why the obvious fix is wrong
Moving the default to ~/.surgewave/plugins looks like the Bowire pattern (data under the user profile rather than next to the executable) but makes the service case worse. A broker runs under a service account. ~ is then the service account's home, not the home of the operator who ran plugins install — so the admin installs into their own profile, the broker reads another, and nothing reports a problem. Two admins on one host would also give one broker two different behaviours depending on who last installed something.
Installed plugins are machine state. The user profile is the wrong scope for them, however right it is for CLI preferences.
Proposed scopes
| Scope | Windows | Linux / macOS | Contents | Lifetime |
|---|---|---|---|---|
| Installation | <install>/plugins |
<install>/plugins |
shipped inside the artefact — publish.ps1 writes here, container images bake here |
replaced wholesale on upgrade |
| Machine state | %ProgramData%\Surgewave\plugins |
/var/lib/surgewave/plugins |
what an operator installs for this host | survives upgrades |
| Machine config | %ProgramData%\surgewave\ |
/etc/surgewave/ |
already implemented in RepositoryConfiguration.GetSearchPaths() |
— |
| User | ~/.surgewave |
~/.surgewave |
CLI preferences, plugin sources, templates | per user |
/var/lib rather than /etc for the state tier: installed plugins are mutable data, not configuration. Note that SpecialFolder.CommonApplicationData maps to /usr/share on .NET for Unix, which is why the existing code branches on OperatingSystem.IsWindows() by hand — the resolver must keep doing that rather than trusting the enum.
Discovery reads installation and machine state, in that order, with the machine tier winning on an id collision and saying so in the log. They are genuinely different categories — one ships with the product, the other is what this host added — in the same way /usr/lib and /usr/local/lib are.
Surgewave:PluginsDirectory keeps overriding everything with a single directory, which is what container images want.
Consequences worth deciding explicitly
Machine scope needs elevation. /var/lib/surgewave and %ProgramData%\Surgewave are not writable by an unprivileged user. plugins install should fail with a message naming the directory and offering --scope user, not fall back silently — a silent fallback is precisely the launcher-dependent behaviour that produced #157. A per-user broker on a dev box is then an explicit choice rather than an accident.
~/.surgewave/connectors has the same defect today. Connectors the broker loads are machine state by the same argument; --install-dir defaults to the user profile. Same fix, same resolver.
Work
- one resolver in
Plugins.Packagingnext toSurgewavePackageConventions, with the scopes above and tests for the platform branches - broker discovery reads both tiers
plugins install/list/uninstalltake--scope machine|userwith machine as default, and print the absolute path they used — plugins install defaults to a directory the broker never reads #157's invisibility was as much about silence as about the pathControl,Connect.WorkerandMarketplacemove onto the resolverpublish.ps1and the docs follow
Closes #157 as part of the work rather than by patching one default.
Activity
feat(plugins): separate the installation from the data it is given
thomas-stegemann commentedon Aug 25, 2026
Broker and CLI are done (d9c92dc); #157 is closed by it.
SurgewaveDataRootandSurgewavePluginDirectorieslive inPlugins.Packaging, 16 tests.Two things came out differently than the issue text assumed.
Loading ignored the configured directory entirely.
EnsurePluginsLoadedhadPath.Combine(AppContext.BaseDirectory, "plugins")hardcoded, whileSurgewave:PluginsDirectorywas honoured when layering plugin default settings and when building the signer. Setting it therefore changed a plugin's configuration without changing which plugins existed. Fixed as part of this.Precedence had to be resolved by plugin id before loading, not during.
TryLoadAssemblyskips assemblies that are already loaded, so whichever scope was visited first would have won silently and the loser would have left no trace. Scopes are now collapsed into an id → directory map first, which is also what makes the shadowing log line possible.Added beyond the original scope, both from review:
SURGEWAVE_DATA_DIRrelocating every scope under one root — a test fixture creates one tree and deletes one tree instead of hunting for state inbin/Debug,binor the repository root depending on how the process started — andSURGEWAVE_INSTANCE/Surgewave:Instanceadding one path segment so several brokers share a machine without sharing state. Unset means the scope is the root itself. The cluster id is deliberately not used for that: two nodes of one cluster on one host share it, and they are the pair that must not share a directory.Verified end to end:
plugins installwith no flags, then a broker with no flags, discovers and activates the plugin;/bowireanswers 200 and reports thesurgewave://protocol. With--Surgewave:Instance=betathe same broker sees ten plugins instead of eleven, andplugins listnames all three searched directories.Still open here:
Control(still the literal"plugins"),Connect.Worker,Marketplace,publish.ps1and the docs. Also~/.surgewave/connectors— connectors the broker loads are machine state by the same argument, and--install-dirstill defaults to the user profile.feat(plugins): one resolver for every process, and a switch for user …
docs(plugins): say where plugins live and who may put them there
fix(cli): config inspection falls back to the machine, not to the CLI…
thomas-stegemann commentedon Aug 25, 2026
Done (262a3fc, a94a673, 4cd309c on top of d9c92dc). Every consumer in the work list is on the shared resolver now.
Control listed a different set of plugins than the broker it was managing, whenever it was started from another directory. Connect.Worker did the same under a comment claiming it matched the broker's precedence — it never did; the broker read
plugins/beside its own executable. Marketplace resolved signer providers that way too, so an upload signed by a plugin-provided signer was rejected as a misconfiguration wherever the marketplace happened to be started.Connectors had the identical split and are fixed with it:
plugins install --from-nugetwrote to~/.surgewave/connectorswhile the Connect plugin scanned a working-directory path. Those two have never named the same directory — the defaults only worked for someone who overrode both.SurgewaveConnectorDirectoriesgives them the same three scopes, CLI default machine scope.publish.ps1needed no change. It writes to$outDir/plugins, which is exactly the installation scope — the bundle was already doing the right thing, it just had no name for it.Added on review:
Surgewave:Plugins:AllowUserScope. A plugin in the user scope is code the host executes that an unprivileged account was able to place on disk — the machine scope needs elevation, a home directory does not — so an administrator deploying a broker as a service can refuse it. The broker says at startup when it did, rather than leaving the plugin silently absent. The setting only binds someone who does not start the process; anyone who does could equally pointSurgewave:PluginsDirectoryelsewhere, so it belongs in the installation's appsettings.json or in machine-scope configuration. The CLI names the policy on a--scope userinstall rather than checking it — it cannot read the configuration of a broker it did not start, and pretending to enforce something it cannot see would be worse than saying it.One change worth flagging: the
"plugins"and"./plugins"defaults became empty strings so "not configured" is representable. Comparing against the literal instead would have treated anyone who deliberately configuredpluginsas having said nothing.Verified: a
--scope userinstall is invisible to a broker started withAllowUserScope=false(ten plugins) and visible to one without it (eleven). Full solution builds clean; 351 plugins, 960 broker, 418 connect, 137 repository, 89 control, 32 tool, 25 marketplace tests green.feat(plugins): separate the installation from the data it is given
feat(plugins): one resolver for every process, and a switch for user …
docs(plugins): say where plugins live and who may put them there
fix(cli): config inspection falls back to the machine, not to the CLI…