Skip to content

Separate installation, machine state and user data for plugins — the service does not run as the admin who installed them #158

Closed

Description

@thomas-stegemann

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.Packaging next to SurgewavePackageConventions, with the scopes above and tests for the platform branches
  • broker discovery reads both tiers
  • plugins install/list/uninstall take --scope machine|user with 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 path
  • Control, Connect.Worker and Marketplace move onto the resolver
  • publish.ps1 and the docs follow

Closes #157 as part of the work rather than by patching one default.

Activity

  1. thomas-stegemann commented on Aug 25, 2026

    @thomas-stegemann
    MemberAuthor

    Broker and CLI are done (d9c92dc); #157 is closed by it. SurgewaveDataRoot and SurgewavePluginDirectories live in Plugins.Packaging, 16 tests.

    Two things came out differently than the issue text assumed.

    Loading ignored the configured directory entirely. EnsurePluginsLoaded had Path.Combine(AppContext.BaseDirectory, "plugins") hardcoded, while Surgewave:PluginsDirectory was 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. TryLoadAssembly skips 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_DIR relocating every scope under one root — a test fixture creates one tree and deletes one tree instead of hunting for state in bin/Debug, bin or the repository root depending on how the process started — and SURGEWAVE_INSTANCE / Surgewave:Instance adding 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 install with no flags, then a broker with no flags, discovers and activates the plugin; /bowire answers 200 and reports the surgewave:// protocol. With --Surgewave:Instance=beta the same broker sees ten plugins instead of eleven, and plugins list names all three searched directories.

    Still open here: Control (still the literal "plugins"), Connect.Worker, Marketplace, publish.ps1 and the docs. Also ~/.surgewave/connectors — connectors the broker loads are machine state by the same argument, and --install-dir still defaults to the user profile.

  2. thomas-stegemann commented on Aug 25, 2026

    @thomas-stegemann
    MemberAuthor

    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-nuget wrote to ~/.surgewave/connectors while 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. SurgewaveConnectorDirectories gives them the same three scopes, CLI default machine scope.

    publish.ps1 needed 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 point Surgewave:PluginsDirectory elsewhere, so it belongs in the installation's appsettings.json or in machine-scope configuration. The CLI names the policy on a --scope user install 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 configured plugins as having said nothing.

    Verified: a --scope user install is invisible to a broker started with AllowUserScope=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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    roadmapTracked on the Surgewave Project board

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions