Files

cproudlock 035419fa51 ADR-015: stop shipping one site's values, and make the rule a gate

The scanner has been reporting the same count for weeks, which is what a rule
that only prints becomes. It now FAILS the build, and it looks where the leaks
actually were: PowerShell, the installer, the seeds, generated JSON, the
frontend - case-insensitively, across plugins, shopdb, scripts, deploy, tools.
A line that is deliberate declares itself with an ADR-015-OK marker and a
reason, so the claim is visible in review instead of tolerated in silence.

What it found, fixed here:

- The shadow client wrote one site's ShopDB URL into HKLM whenever the registry
  disagreed. At the site it was written for that reads as healing drift;
  anywhere else it overwrites the site's own address on every enforce cycle,
  and the site cannot win because the cycle repeats. The bay's value now wins,
  an explicit -BaseUrl seeds it, and with neither there is nothing honest to
  write, so it says so and skips.
- The kiosk dispatcher fell back to one plant's host when HKLM was unset, so a
  kiosk elsewhere quietly opened a server it has no business reaching. The
  fallback is now this site's site_base_url, baked in at seed time, and the
  dispatcher refuses rather than guessing when neither is set. Its legacy
  shortcut matcher derives the host from that URL instead of naming one.
- The OpenAPI generator hardcoded a production hostname into every spec it
  generated, which then published to a public wiki. The relative mount is the
  only server it can honestly name; a site passes its own by environment.
- Placeholders and examples in the UI and the client help offered real internal
  subnets and a real production URL. They now use documentation ranges.

Both publication gates - the export scrub and the docs publishability test -
carry the site patterns, which neither did. One plant's hostname, FQDN and
internal networks are out of the documentation and the generated specs.

Comments naming the reference site are reworded rather than deleted: the
reasoning is worth keeping, the plant name is not what makes it true.

2026-08-14 13:47:39 -04:00

5.7 KiB

Raw Blame History

ADR-015: Where a site's own data is allowed to live

Status: ACCEPTED
Date: 2026-08-11
Deciders: cproudlock
Relates to: ADR-004 (per-site instances, not multi-tenant), ADR-013 (plugin catalog + lean per-site builds), ADR-014 (schema-lean per-site builds)

Context

ShopDB is built as a product several GE Aerospace sites can adopt (ADR-004: each site runs its own instance). It is also developed at one site, West Jefferson, against that site's live fleet. Every feature therefore arrives carrying that site's hostnames, networks, share paths and vocabulary, and the fastest way to ship any of them is to write the value where the code needs it.

That is not a hypothetical drift. A scan of plugins/ and shopdb/ for a site host, a site FQDN or a site network returns 19 hits, of which roughly 8 are a shipped default or a hardcode rather than a comment:

plugins/geenforce/seed_display_scope.py baked one site's own ShopDB URL and device.geaerospace.net into an inline PowerShell payload. A sister site could not override either without editing the source. FIXED 2026-08-14: the kiosk base URL now comes from the site_base_url setting at seed time and from HKLM at run time, and the dispatcher refuses rather than guessing when neither is set.
plugins/backups/services/registry.py defaults the backup share root to a WJ UNC path.
shopdb/core/api/settings.py ships device.geaerospace.net and Printer-{ip}.printer.geaerospace.net as SETTING DEFAULTS, so another site inherits WJ's domain silently until someone notices.
shopdb/core/models/dashboarddefault.py holds the same domain a second time as a module constant, and plugins/computers/api/routes.py a third time as a literal fallback.

The problem is not that site-specific values exist - they must. It is that the repository already has three good mechanisms for them and no rule about which to use, so each new value lands wherever was convenient. The result reads as drift because it is unmanaged, not because any single choice was wrong.

Nothing here is a security matter: these are internal hostnames on an air-gapped network, and tests/test_docs_publishable.py already gates what reaches the public wiki. This is about whether a sister site can adopt the product without reading our source.

Decision

A site's own data lives in one of three places, in this order of preference.

1. A setting, with a NEUTRAL default. Anything an operator could plausibly change: hostnames, domains, share paths, networks, base URLs, label prefixes. The default that ships must be blank or generic, never one site's value. Blank must be a working state - code reads the setting and degrades sensibly, the way display_fqdn_domain already treats blank as "use the hostname as-is". A site-specific default is the failure mode this ADR exists to stop: it is invisible, it looks deliberate, and it is wrong everywhere except here.

2. A site-namespaced directory. Anything that is genuinely one site's and will never be another's, such as the West Jefferson import loader at scripts/site_imports/wjf/. Never reached by another site's build.

3. Seed data, not code. Vocabularies and catalogs, loaded by flask seed and editable per site afterwards.

Fleet-wide convention is NOT site-specific. The gea-shopfloor-* imaging types are a GE fleet taxonomy, not one site's data, and they already carry a per-site override through the pctypemap_* settings. They are out of scope here.

Comments and documentation may name a site where it explains WHY - "part markers share a machine number at West Jefferson" is a fact a maintainer needs. Prefer phrasing the rule generally and the example specifically.

Enforcement

scripts/check-naming-and-style.sh, which already runs in CI, greps plugins/ and shopdb/ for a site host, a site FQDN or a site network, excluding tests and site_imports/.

It ships in REPORT-ONLY mode. It prints findings and does not fail the build, because turning a 19-item backlog into a hard gate on the day it lands blocks every unrelated commit until someone works through it. Set SITE_LITERALS_ENFORCE=1 to make it a gate; do that once the real hardcodes below are cleared.

Consequences

Positive:

A sister site can adopt without reading our source for values it must change.
The backlog is visible and counted rather than felt.
New site-specifics are caught at commit time, in the same place the naming rules are already enforced, so there is nothing new to remember.

Negative:

Report-only means the rule is advisory until someone flips it, and an advisory rule can be ignored.
A neutral default is more code than a working one: every read needs a blank case, which is a real cost paid at every call site.
The pattern list is a denylist and will miss a site value it has not been taught. It catches drift, not everything.

Backlog

Real hardcodes and site-specific defaults, to clear before enforcing:

plugins/geenforce/seed_display_scope.py - kiosk base URL, FQDN domain, and the legacy-shortcut sweep pattern
plugins/backups/services/registry.py - DEFAULTSHAREROOT
shopdb/core/api/settings.py - display_fqdn_domain and the printer hostname pattern defaults
shopdb/core/models/dashboarddefault.py - DEFAULT_DISPLAY_FQDN_DOMAIN
plugins/computers/api/routes.py - literal fallback duplicating that default

The domain appears three times in three files, which is its own defect: one setting, one default, one read.

Cosmetic mentions in comments and UI placeholder text are acceptable under this ADR and are not part of the backlog, with one exception worth fixing when convenient: the GE-Enforce settings page shows WJ's real CIDRs as its placeholder, which every site sees.

5.7 KiB Raw Blame History