Skip to content

Add a machine scope and an instance segment to BowireStorageRoot #616

Closed

Description

@thomas-stegemann

Context

BowireStorageRoot already gets the hard part right: data lives under ~/.bowire/ rather than next to the executable, and a project can opt in to .bowire/ via its manifest — deliberately not via a CLI flag, so the answer does not depend on who launched the process. Surgewave has now adopted the same separation (Kuestenlogik/Surgewave#158) and hit two cases this does not cover.

What is missing

A machine scope. ~/.bowire/ is the user's home. A Bowire instance that runs as a service — a shared team instance rather than someone's desktop tool — resolves ~ to the service account's profile, not to the operator's. In Surgewave this produced a real defect: an admin installed a plugin, the tool confirmed it, and the broker never saw it, because they were looking at two different profiles with the same name (Kuestenlogik/Surgewave#157). Anything a service reads needs a scope that does not depend on the account:

Windows Linux
Machine %ProgramData%\Bowire /var/lib/bowire
User ~/.bowire ~/.bowire

Note that SpecialFolder.CommonApplicationData maps to /usr/share on .NET for Unix, which is for static package data rather than for state a service writes — the platform branch has to be written by hand.

An instance segment. Several Bowire instances on one machine currently share ~/.bowire/. BOWIRE_INSTANCE adding a single path segment separates them, the way PGDATA and GEOSERVER_DATA_DIR do. Unset should mean the root itself, so nothing moves for the single-instance case. Reject a name that contains a path separator or that collides with a directory the root already owns — with no instance set the scope is the root, so an instance named after one of those would share state with an unnamed one.

One override for tests. BOWIRE_DATA_DIR pointing every scope at one directory is what makes a test fixture able to create one tree and delete one tree, instead of hunting for state next to whichever output directory the run happened to use.

The project opt-in stays exactly as it is — it answers a different question (which checkout owns this data) and it answers it well.

Reference

SurgewaveDataRoot and SurgewavePluginDirectories in Kuestenlogik/Surgewave (commit d9c92dc), with tests covering the platform branch, the instance rules and the de-duplication that a redirected root needs.

Activity

  1. thomas-stegemann commented on Aug 25, 2026

    @thomas-stegemann
    MemberAuthor

    Looked at this while working nearby, and there is a prerequisite worth pulling into the issue: a machine scope and an instance segment added to BowireStorageRoot would not reach most of the code that stores things.

    What the audit found

    BowireStorageRoot.Apply() sets BowireUserContext.Current, and everything that asks BowireUserContext for a path follows it. But 14 files across 6 assemblies build the path themselves instead:

    Assembly Files
    Kuestenlogik.Bowire Auth/IBowireUserStore.cs (UserProfileRoot), BowireServiceCollectionExtensions.cs (×2), Endpoints/BowirePluginEndpoints.cs, Plugins/PluginUpdateCheckService.cs, Plugins/Sidecar/SidecarPluginDiscovery.cs, Proxy/BowireProxyCertificateAuthority.cs, Sources/BowireCatalogueOverride.cs, Sources/LocalCatalogueProvider.cs
    Kuestenlogik.Bowire.Mcp BowireMcpResources.cs (×2), BowireMcpTools.cs, BowireMcpTypedUrlStore.cs
    Kuestenlogik.Bowire.Tool Plugins/BowirePluginOptions.cs
    Kuestenlogik.Bowire.Security.Scanner VulnDbCache.cs
    Kuestenlogik.Bowire.Monitoring MonitoringServiceCollectionExtensions.cs

    Each one is Path.Combine(Environment.GetFolderPath(SpecialFolder.UserProfile), ".bowire", …) — the string ".bowire" written out sixteen times.

    Alongside them sit per-feature environment overrides that each resolve on their own terms: BOWIRE_CATALOGUE_CONFIG_PATH, BOWIRE_CATALOGUE_PATH, BOWIRE_PLUGIN_DIR. And several carry their own fallback rules — VulnDbCache drops to %TEMP%/bowire/vulndb when the profile is empty, BowireCatalogueOverride.ResolvePath() returns "", others would produce .bowire relative to the working directory.

    So the defect this issue exists to fix reappears per feature. A service instance that resolves ~ to its service account gets the right answer for anything routed through BowireUserContext and the wrong one for the plugin directory, the proxy CA, the vuln-db cache, the catalogue config and the MCP stores. Which is exactly the Surgewave failure — an admin installs a plugin, the tool confirms it, the broker never sees it — and BOWIRE_INSTANCE would separate instances everywhere except where they actually collide.

    Proposed shape

    An injectable resolver rather than more static helpers, so that scope selection is a decision made once and passed down:

    public interface IBowirePathResolver
    {
        // Scope decides the root; the segments are the relative path under it.
        string Resolve(BowireStorageScope scope, params string[] segments);
    }
    
    public enum BowireStorageScope
    {
        Data,      // whatever BowireStorageRoot resolved: project .bowire/ or the user/machine root
        Machine,   // %ProgramData%\Bowire | /var/lib/bowire — survives which account runs the service
        Cache,     // discardable: vuln-db, update-check stamps
    }
    • Registered in AddBowire(); every consumer above takes it as a constructor dependency.
    • BOWIRE_DATA_DIR and BOWIRE_INSTANCE are read once, inside the resolver — which is what makes the test-fixture override from this issue's third bullet actually cover everything, rather than every store needing its own escape hatch.
    • The per-feature env vars stay working as narrower overrides, but they override a resolved path instead of replacing the resolution.
    • The static BowireUserContext path stays for now as a thin forwarder, so this does not have to land as one commit.

    The two hard cases are worth naming up front:

    • DefaultBowireUserStore.UserProfileRoot is a static property that half the codebase reads. It becomes the resolver's default rather than the thing everyone calls.
    • BowirePluginOptions.DefaultDirectory is a static in the Tool, read before any container exists. That one needs the resolver to be constructible without DI, which is fine — a parameterless new with the same defaults, with DI supplying a configured one where a container exists.

    Happy to take this on; it is mostly mechanical once the resolver exists, and it makes the machine scope and instance segment land everywhere in one move rather than one store at a time.

    (Unrelated but adjacent: --port-file from #615 is not affected — the caller names an absolute path, so there is no resolution to route.)

  2. thomas-stegemann commented on Aug 25, 2026

    @thomas-stegemann
    MemberAuthor

    The consolidation from the comment above landed in d6a2846d — the prerequisite, not the feature. Here is what is now true and what is left.

    Done

    One resolver. IBowirePathResolver answers for two scopes: Data (whatever BowireStorageRoot decided — the project's .bowire/ or the user root) and Machine (%ProgramData%\Bowire | /var/lib/bowire). Injected via AddBowire(), reachable through a BowirePaths facade for the call sites that resolve during type initialisation, before any container exists.

    BOWIRE_INSTANCE and BOWIRE_DATA_DIR are read in exactly one place. Instance names are validated rather than accepted quietly: anything that is not a single path segment, and anything colliding with a directory the root already owns (plugins, workspaces, recordings, flows, cache, certs, logs, presets, mocks) — because with no instance set the root is the scope, so such a name would silently share state with an unnamed instance.

    Fourteen files stopped building the path themselves — 16 hand-rolled resolutions down to 1, which is DefaultBowireUserStore.UserProfileRoot, the value the resolver's own default reads.

    Three defects fell out of having one place instead of sixteen:

    1. Static fields pinned the pre-Apply() path. BowireStorageRoot.Apply() runs when the host is built, which can be after a type is first touched — so PluginUpdateCheckService.DefaultPluginDir, BowirePluginOptions.DefaultDirectory and SidecarPluginDiscovery.DefaultPluginRoot captured the user root and then ignored a project that had opted into .bowire/ storage. They are properties now.
    2. The empty-home guards disagreed. Two fell back to %TEMP%, one returned "" — which made BowireCatalogueOverrideStore silently never persist — and the rest would have produced a relative .bowire next to the working directory. One guard now, in the resolver, returning a usable absolute root.
    3. MCP's HomeDirOverride was three copies across three types, so "redirect everything MCP reads" was a promise each new call site had to remember. One property, in McpPaths.

    A convention test scans src/ for either half of the old pattern and fails with the offending file list.

    Tests: 24 for the resolver, 2 for the convention. Core 2830/2831 (the one failure is a pre-existing cancellation-timing flake in ProxyCommandTests, green in isolation), MCP 134/134, Benchmarking 95/95, Monitoring 118/118.

    Docs: architecture/storage-locations.md.

    Still open — and one that needs your call

    The scopes exist; nothing uses Machine yet. That is the actual feature and it is deliberately a separate step: routing a store to the machine scope moves its data, so each one is a decision (the plugin directory is the obvious first candidate, since it is the one the Surgewave defect was about).

    Two files resolve against the working directory, not the user profile — BowireBenchmarkScheduleStore and ContractResultStore, both Path.Combine(Directory.GetCurrentDirectory(), ".bowire", …). The convention test found them; I exempted them rather than sweeping them in, because they answer a different question: a contract result and a benchmark schedule belong to the checkout being tested, and both already take an explicit rootPath that CI passes. Routing them through the Data scope would move them out of the repo for anyone who does not pass one — a product decision, not a cleanup. Worth deciding here.

  3. thomas-stegemann commented on Aug 28, 2026

    @thomas-stegemann
    MemberAuthor

    Shipped in 9e8718e (feat(storage): one resolver decides where Bowire stores things).

    All three gaps this issue named are closed:

    • Machine scope — BowireStorageScope.Machine resolves to %ProgramData%\Bowire on Windows and /var/lib/bowire on Linux. The platform branch is written by hand, exactly as the issue warned: SpecialFolder.CommonApplicationData maps to /usr/share on .NET for Unix, which is for static package data, not for state a service writes.
    • Instance segment — BOWIRE_INSTANCE adds one segment under every root. Unset means the root itself, so nothing moves for the single-instance case. A name containing a path separator is refused, and so is one colliding with a directory the root already owns (plugins, workspaces, recordings, …) — with no instance set the scope is the root, so such a name would silently share state with an unnamed instance.
    • Test override — BOWIRE_DATA_DIR redirects every scope at one directory, so a fixture creates one tree and deletes one tree.

    The project opt-in is untouched, as intended.

    Covered by 19 tests in BowirePathResolverTests, plus StoragePathConventionTests guarding against new hand-rolled Path.Combine(home, ".bowire", …) call sites. Documented in docs/architecture/storage-locations.md.

    The machine scope is already carrying its first consumer: the machine-wide plugin tier from #28 Phase D resolves through it.

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

    No labels
    No labels

    Projects

    • Status
      Done

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions