From f84e0c3474a24d0910e0e1c74e3ebb198ed70f26 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 3 Jun 2026 15:50:13 -0400 Subject: [PATCH] docs(audit): apply global term/path substitutions across living docs --- CLAUDE.md | 12 ++++++------ clients/python/PythonClientDesign.md | 2 +- docs/ClientLibrariesDesign.md | 2 +- docs/ClientPackaging.md | 18 +++++++++--------- docs/ClientProtoGeneration.md | 4 ++-- docs/DashboardInterfaceDesign.md | 2 +- docs/Diagnostics.md | 4 ++-- docs/GalaxyRepository.md | 6 +++--- docs/GatewayConfiguration.md | 8 ++++---- docs/GatewayDashboardDesign.md | 8 ++++---- docs/GatewayProcessDesign.md | 12 ++++++------ docs/GatewayTesting.md | 2 +- docs/MxAccessWorkerInstanceDesign.md | 2 +- docs/WorkerSta.md | 4 ++-- docs/style-guides/JavaStyleGuide.md | 2 +- docs/style-guides/PythonStyleGuide.md | 4 ++-- 16 files changed, 46 insertions(+), 46 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8cf6ea1..a5cb7ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -19,7 +19,7 @@ The worker must do all MXAccess COM calls on its dedicated STA thread, and the S ```powershell # Full solution build (gateway, worker, contracts, tests) -dotnet build src/MxGateway.sln +dotnet build src/ZB.MOM.WW.MxGateway.slnx # Worker must be built x86 — the gateway looks for MxGateway.Worker.exe under bin\x86 dotnet build src/MxGateway.Worker/MxGateway.Worker.csproj -p:Platform=x86 @@ -29,10 +29,10 @@ dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj dotnet test src/MxGateway.Worker.Tests/MxGateway.Worker.Tests.csproj -p:Platform=x86 # Run gateway locally (defaults bound under MxGateway:* in src/MxGateway.Server/appsettings.json) -dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj +dotnet run --project src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj # API-key admin CLI (same exe, "apikey" subcommand) -dotnet run --project src/MxGateway.Server/MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin +dotnet run --project src/ZB.MOM.WW.MxGateway.Server/ZB.MOM.WW.MxGateway.Server.csproj -- apikey create --display-name "dev" --scopes session,invoke,event,metadata,admin ``` Single test by name (xUnit `--filter`): @@ -54,7 +54,7 @@ Live LDAP tests use `MXGATEWAY_RUN_LIVE_LDAP_TESTS=1`. See `docs/GatewayTesting. Each language client is in `clients//` with its own README. They all consume the shared `.proto` files in `src/MxGateway.Contracts/Protos`: -- `clients/dotnet`: `dotnet build clients/dotnet/MxGateway.Client.sln` +- `clients/dotnet`: `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` - `clients/python`: `python -m pip install -e ".[dev]"; python -m pytest` - `clients/rust`: `cargo test --workspace; cargo clippy --workspace --all-targets -- -D warnings` - `clients/java`: `gradle test` (Java 21) @@ -90,7 +90,7 @@ When source code changes, build and test the affected component before reporting | Contracts or `.proto` files | regenerate generated code, then build gateway, worker, and every generated client touched by the contract | | Gateway server, sessions, workers, gRPC, dashboard, metrics | `dotnet build src/MxGateway.Server` and run affected gateway / fake-worker tests | | Worker IPC, STA, MXAccess, conversion | `dotnet build src/MxGateway.Worker -p:Platform=x86` and run worker tests | -| .NET client | `dotnet build clients/dotnet/MxGateway.Client.sln` and run its tests | +| .NET client | `dotnet build clients/dotnet/ZB.MOM.WW.MxGateway.Client.slnx` and run its tests | | Go client | `gofmt`, `go build ./...`, `go test ./...` from `clients/go` | | Rust client | `cargo fmt`, `cargo check --workspace`, `cargo test --workspace`, `cargo clippy --all-targets -- -D warnings` from `clients/rust` | | Python client | `python -m pytest` from `clients/python` | @@ -116,7 +116,7 @@ External analysis sources referenced by design docs: Gateway gRPC clients authenticate with an API key in metadata: `authorization: Bearer mxgw__`. Keys are stored hashed (with a peppered SHA) in a gateway-owned SQLite DB (default `C:\ProgramData\MxGateway\gateway-auth.db`). Scopes (`session`, `invoke`, `event`, `metadata`, `admin`) gate specific RPCs; missing → `Unauthenticated`, insufficient → `PermissionDenied`. The `apikey` subcommand on the server exe manages keys; see `src/MxGateway.Server/Security/Authentication/`. -Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Admin` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `__Host-MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled. +Dashboard auth is LDAP-backed (separate from the gRPC API-key model). `/login` binds against `MxGateway:Ldap` and maps the user's LDAP groups to `Administrator` or `Viewer` via `MxGateway:Dashboard:GroupToRole`, then issues an HTTP-only secure `MxGatewayDashboard` cookie. SignalR hubs at `/hubs/{snapshot,alarms,events}` accept either the cookie or a 30-minute bearer minted at `/hubs/token`. `Dashboard:AllowAnonymousLocalhost` bypasses auth on loopback when enabled. ## Process / Platform Notes diff --git a/clients/python/PythonClientDesign.md b/clients/python/PythonClientDesign.md index 9eb0d5c..4dd70c1 100644 --- a/clients/python/PythonClientDesign.md +++ b/clients/python/PythonClientDesign.md @@ -212,7 +212,7 @@ Use bounded smoke flow and always attempt `close_session` in `finally`. Use `pyproject.toml`. Publishable package name should be stable, for example: ```text -mxaccess-gateway-client +zb-mom-ww-mxaccess-gateway-client ``` Generated protobuf code should be regenerated through a documented command, not diff --git a/docs/ClientLibrariesDesign.md b/docs/ClientLibrariesDesign.md index f0652ff..c29fb1d 100644 --- a/docs/ClientLibrariesDesign.md +++ b/docs/ClientLibrariesDesign.md @@ -407,7 +407,7 @@ The stable client proto manifest defines the generated-code directories: clients/dotnet/generated clients/go/internal/generated clients/rust/src/generated -clients/python/src/mxgateway/generated +clients/python/src/zb_mom_ww_mxgateway/generated clients/java/src/main/generated ``` diff --git a/docs/ClientPackaging.md b/docs/ClientPackaging.md index d434ea4..71d341c 100644 --- a/docs/ClientPackaging.md +++ b/docs/ClientPackaging.md @@ -113,7 +113,7 @@ Pop-Location ## Rust -The Rust workspace builds the `mxgateway-client` library crate and the `mxgw` +The Rust workspace builds the `zb-mom-ww-mxgateway-client` library crate and the `mxgw` CLI crate. `build.rs` generates `tonic` and `prost` modules into Cargo build output on each build that needs updated protobuf output. @@ -156,8 +156,8 @@ Pop-Location ## Python -The Python package is `mxaccess-gateway-client`. Generated modules live under -`clients/python/src/mxgateway/generated`. +The Python package is `zb-mom-ww-mxaccess-gateway-client`. Generated modules live under +`clients/python/src/zb_mom_ww_mxgateway/generated`. Regenerate the Python bindings: @@ -184,7 +184,7 @@ Push-Location clients/python mxgw-py version --json mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json -python -m mxgateway_cli version --json +python -m zb_mom_ww_mxgateway_cli version --json Pop-Location ``` @@ -198,7 +198,7 @@ Regenerate Java bindings: ```powershell Push-Location clients/java -gradle :mxgateway-client:generateProto +gradle :zb-mom-ww-mxgateway-client:generateProto Pop-Location ``` @@ -214,7 +214,7 @@ Create local library and CLI artifacts: ```powershell Push-Location clients/java -gradle :mxgateway-client:jar :mxgateway-cli:installDist +gradle :zb-mom-ww-mxgateway-client:jar :zb-mom-ww-mxgateway-cli:installDist Pop-Location ``` @@ -222,9 +222,9 @@ Run the CLI through Gradle: ```powershell Push-Location clients/java -gradle :mxgateway-cli:run --args="version --json" -gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json" -gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json" +gradle :zb-mom-ww-mxgateway-cli:run --args="version --json" +gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json" +gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json" Pop-Location ``` diff --git a/docs/ClientProtoGeneration.md b/docs/ClientProtoGeneration.md index 306209d..c790f3b 100644 --- a/docs/ClientProtoGeneration.md +++ b/docs/ClientProtoGeneration.md @@ -77,7 +77,7 @@ The manifest declares these generated-code directories: | .NET | `clients/dotnet/generated` | | Go | `clients/go/internal/generated` | | Rust | `clients/rust/src/generated` | -| Python | `clients/python/src/mxgateway/generated` | +| Python | `clients/python/src/zb_mom_ww_mxgateway/generated` | | Java | `clients/java/src/main/generated` | Only generator output belongs in these directories. Handwritten client wrappers @@ -142,7 +142,7 @@ cargo check --workspace ``` Python clients should use `grpc_tools.protoc` and write generated modules under -`clients/python/src/mxgateway/generated` so imports stay separate from +`clients/python/src/zb_mom_ww_mxgateway/generated` so imports stay separate from handwritten async wrappers. The Python scaffold provides a repo-local generation script: diff --git a/docs/DashboardInterfaceDesign.md b/docs/DashboardInterfaceDesign.md index 237fdd9..c0dab3e 100644 --- a/docs/DashboardInterfaceDesign.md +++ b/docs/DashboardInterfaceDesign.md @@ -288,7 +288,7 @@ Use this checklist when applying the design to another project: - Use top-bordered sections for page groups instead of nested cards. - Centralize formatting and redaction outside Razor markup. - Hide every destructive admin affordance from viewers; render it only for - the `Admin` role and re-check the role server-side on every invocation. + the `Administrator` role and re-check the role server-side on every invocation. - Route every destructive action (Close session, Kill worker, Rotate / Revoke / Delete API key) through the shared `ConfirmDialog` component so the operator always gets one explicit confirmation step before the call diff --git a/docs/Diagnostics.md b/docs/Diagnostics.md index 8d966ab..ecaab5a 100644 --- a/docs/Diagnostics.md +++ b/docs/Diagnostics.md @@ -162,7 +162,7 @@ public static IApplicationBuilder UseGatewayRequestLoggingScope(this IApplicatio { ILogger logger = context.RequestServices .GetRequiredService() - .CreateLogger("ZB.MOM.WW.MxGateway.Request"); + .CreateLogger("MxGateway.Request"); using IDisposable? scope = logger.BeginGatewayScope(new GatewayLogScope( SessionId: ReadHeader(context, SessionIdHeaderName), @@ -188,7 +188,7 @@ The scope is keyed off four custom headers and the standard `authorization` head The numeric headers use `int.TryParse` and `ulong.TryParse`; missing or unparseable values become `null` and are dropped by `GatewayLogScope.ToDictionary`. This keeps the middleware tolerant of clients that do not yet emit every header, which matters because the earliest call in a session (`OpenSession`) has no `SessionId` to send. -The logger category is `ZB.MOM.WW.MxGateway.Request`, which lets operators filter the request scope events independently from per-component categories. +The logger category is `MxGateway.Request`, which lets operators filter the request scope events independently from per-component categories. ### Pipeline ordering diff --git a/docs/GalaxyRepository.md b/docs/GalaxyRepository.md index ff61d60..558a062 100644 --- a/docs/GalaxyRepository.md +++ b/docs/GalaxyRepository.md @@ -419,17 +419,17 @@ embedded in the status detail. The gateway's Blazor dashboard surfaces a Galaxy summary in two places: -- An overview card on `/dashboard` showing connectivity status, last deploy +- An overview card on `/` showing connectivity status, last deploy timestamp, object count (with area count), attribute total, historized and alarm counts, and last successful refresh. -- A dedicated `/dashboard/galaxy` page with object-category and top-template +- A dedicated `/galaxy` page with object-category and top-template breakdowns plus a Sync Info table covering last successful refresh, last attempt, refresh interval, redacted connection string, and command timeout. Both views are projected from the same `IGalaxyHierarchyCache` that backs the gRPC service. The dashboard does not run its own refresh — when the background `GalaxyHierarchyRefreshService` updates the cache, both the -overview card and the `/dashboard/galaxy` page pick up the new state on the +overview card and the `/galaxy` page pick up the new state on the next dashboard tick. When SQL is unreachable, the cache retains the previous data and flips `Status` to `Stale` or `Unavailable`; the dashboard surfaces that as a yellow or red status badge plus the truncated error. diff --git a/docs/GatewayConfiguration.md b/docs/GatewayConfiguration.md index 07c1c04..40c60bd 100644 --- a/docs/GatewayConfiguration.md +++ b/docs/GatewayConfiguration.md @@ -52,7 +52,7 @@ paths, timeouts, queue sizes, enum values, or protocol values are invalid. "RecentSessionLimit": 200, "ShowTagValues": false, "GroupToRole": { - "GwAdmin": "Admin", + "GwAdmin": "Administrator", "GwReader": "Viewer" } }, @@ -153,7 +153,7 @@ the affected stream while the MXAccess session remains active. | `MxGateway:Dashboard:RecentFaultLimit` | `100` | Maximum number of fault summaries projected into each dashboard snapshot. | | `MxGateway:Dashboard:RecentSessionLimit` | `200` | Maximum number of session summaries projected into each dashboard snapshot. | | `MxGateway:Dashboard:ShowTagValues` | `false` | Reserved display control for tag values. The dashboard does not show full tag values by default. | -| `MxGateway:Dashboard:GroupToRole` | _(empty)_ | LDAP group → dashboard role mapping. Keys are LDAP group names (short CN or full DN — leading-RDN match). Values must be `Admin` (read/write, API-key CRUD) or `Viewer` (read-only). A user whose LDAP groups don't intersect this map cannot sign in; with no mapping at all, only the loopback bypass admits anyone. | +| `MxGateway:Dashboard:GroupToRole` | _(empty)_ | LDAP group → dashboard role mapping. Keys are LDAP group names (short CN or full DN — leading-RDN match). Values must be `Administrator` (read/write, API-key CRUD) or `Viewer` (read-only). A user whose LDAP groups don't intersect this map cannot sign in; with no mapping at all, only the loopback bypass admits anyone. | `SnapshotIntervalMilliseconds` must be greater than zero. `RecentFaultLimit` and `RecentSessionLimit` must be greater than or equal to zero. @@ -166,10 +166,10 @@ users) but practical deployments populate at least one Admin group. Three authorization policies are registered out of these options: - `MxGateway.Dashboard.Viewer` — gates the Razor component routes. Satisfied by - either dashboard role (Admin or Viewer), by `AllowAnonymousLocalhost` on + either dashboard role (Administrator or Viewer), by `AllowAnonymousLocalhost` on loopback, or by `Authentication.Mode = Disabled`. - `MxGateway.Dashboard.Admin` — gates write-capable surfaces (API-key CRUD). - Satisfied only by the Admin role (same environmental bypasses). + Satisfied only by the Administrator role (same environmental bypasses). - `MxGateway.Dashboard.HubClients` — attached to the SignalR hubs. Accepts either the dashboard cookie scheme or the `MxGateway.Dashboard.HubToken` bearer scheme (used by SignalR's WebSocket upgrade path where the HttpOnly diff --git a/docs/GatewayDashboardDesign.md b/docs/GatewayDashboardDesign.md index 1d442f3..bea9be8 100644 --- a/docs/GatewayDashboardDesign.md +++ b/docs/GatewayDashboardDesign.md @@ -288,7 +288,7 @@ it opt-in and redacted. ### Browse page -`/dashboard/browse` lets an operator explore the Galaxy tag hierarchy and watch +`/browse` lets an operator explore the Galaxy tag hierarchy and watch live values. The tree is built in-process by `DashboardBrowseTreeBuilder` from `IGalaxyHierarchyCache.Current` — the same cache the Galaxy page reads — so a render costs no gRPC call and no SQL round-trip. Each node shows its child @@ -306,7 +306,7 @@ diagnostic session/worker views. ### Alarms page -`/dashboard/alarms` lists the alarms the gateway's central alarm monitor +`/alarms` lists the alarms the gateway's central alarm monitor currently holds as Active or ActiveAcked, refreshed every three seconds. It defaults to showing unacknowledged `Active` alarms; filters add acknowledged alarms and narrow by area, severity range, and a reference/source/description @@ -335,7 +335,7 @@ the monitor never starts and the cache stays empty. ### API keys page -`/dashboard/apikeys` lists the gateway's API keys and, for authorized +`/apikeys` lists the gateway's API keys and, for authorized operators, manages them. It reads key metadata through the same `IApiKeyAdminStore` the `apikey` CLI uses, so the dashboard and the CLI act on one source of truth. @@ -421,7 +421,7 @@ Implemented behavior: `ClaimTypes.Role` claims, alongside the per-group `mxgateway:ldap_group` claims; - a successful login signs in the `MxGateway.Dashboard` cookie scheme - (`__Host-MxGatewayDashboard`, HttpOnly, SameSite=Strict, Secure); + (`MxGatewayDashboard`, HttpOnly, SameSite=Strict, Secure); - a user with no matching group cannot sign in — the login screen returns the generic credential-rejected message; - antiforgery tokens guard the login and logout POSTs. diff --git a/docs/GatewayProcessDesign.md b/docs/GatewayProcessDesign.md index ae5b5ca..bfeb38f 100644 --- a/docs/GatewayProcessDesign.md +++ b/docs/GatewayProcessDesign.md @@ -247,12 +247,12 @@ Technology: Suggested routes: ```text -/dashboard -/dashboard/sessions -/dashboard/sessions/{sessionId} -/dashboard/workers -/dashboard/events -/dashboard/settings +/ +/sessions +/sessions/{sessionId} +/workers +/events +/settings ``` Dashboard pages: diff --git a/docs/GatewayTesting.md b/docs/GatewayTesting.md index f099dc8..d3cc886 100644 --- a/docs/GatewayTesting.md +++ b/docs/GatewayTesting.md @@ -320,7 +320,7 @@ writes its `{"error":...}` envelope and the loop continues; the harness treats that envelope as the operation failure (used by the parity and auth phases). Before the per-client phases run, the script builds the .NET CLI -(`dotnet build`) and installs the Java CLI (`gradle :mxgateway-cli:installDist`) +(`dotnet build`) and installs the Java CLI (`gradle :zb-mom-ww-mxgateway-cli:installDist`) once, so the `batch` process launches straight from the compiled exe / the installed launcher. The Go, Rust, and Python batch processes are launched via `go run` / `cargo run` / `python -m`, which compile-or-start once when that diff --git a/docs/MxAccessWorkerInstanceDesign.md b/docs/MxAccessWorkerInstanceDesign.md index d490f59..bd253f1 100644 --- a/docs/MxAccessWorkerInstanceDesign.md +++ b/docs/MxAccessWorkerInstanceDesign.md @@ -251,7 +251,7 @@ The loop should update a heartbeat timestamp after: - processing an MXAccess event. `StaRuntime` implements this runtime boundary in the worker. It starts one -background thread named `ZB.MOM.WW.MxGateway.Worker.STA`, sets it to `ApartmentState.STA`, +background thread named `MxGateway.Worker.STA`, sets it to `ApartmentState.STA`, initializes COM through `StaComApartmentInitializer`, and runs `StaMessagePump`. Commands are scheduled through `InvokeAsync`; the command queue signals an `AutoResetEvent` so `MsgWaitForMultipleObjectsEx` can wake the diff --git a/docs/WorkerSta.md b/docs/WorkerSta.md index 8c04661..8d20685 100644 --- a/docs/WorkerSta.md +++ b/docs/WorkerSta.md @@ -20,13 +20,13 @@ The installed MXAccess interop assembly declares an `Apartment` threading model ## STA Thread Initialization -`StaRuntime`'s constructor configures a background `Thread` named `ZB.MOM.WW.MxGateway.Worker.STA` and forces it into `ApartmentState.STA` before the thread starts. `Start()` releases the thread and then blocks on `startedEvent` so callers observe a fully-initialized apartment (or a captured `startupException`) before the first `InvokeAsync` call: +`StaRuntime`'s constructor configures a background `Thread` named `MxGateway.Worker.STA` and forces it into `ApartmentState.STA` before the thread starts. `Start()` releases the thread and then blocks on `startedEvent` so callers observe a fully-initialized apartment (or a captured `startupException`) before the first `InvokeAsync` call: ```csharp staThread = new Thread(ThreadMain) { IsBackground = true, - Name = "ZB.MOM.WW.MxGateway.Worker.STA" + Name = "MxGateway.Worker.STA" }; staThread.SetApartmentState(ApartmentState.STA); ``` diff --git a/docs/style-guides/JavaStyleGuide.md b/docs/style-guides/JavaStyleGuide.md index b46036e..539877b 100644 --- a/docs/style-guides/JavaStyleGuide.md +++ b/docs/style-guides/JavaStyleGuide.md @@ -22,7 +22,7 @@ library, CLI, and tests. ## Packages -- Use lowercase package names under `com.dohertylan.mxgateway`. +- Use lowercase package names under `com.zb.mom.ww.mxgateway`. - Keep client library code separate from CLI code. - Keep generated protobuf classes in a generated package. - Do not expose implementation-only transport helpers as public API. diff --git a/docs/style-guides/PythonStyleGuide.md b/docs/style-guides/PythonStyleGuide.md index a1bd163..e0241ef 100644 --- a/docs/style-guides/PythonStyleGuide.md +++ b/docs/style-guides/PythonStyleGuide.md @@ -24,8 +24,8 @@ CLI, and tests. ## Package Structure -- Put library code under `src/mxgateway/`. -- Put CLI entry points under `src/mxgateway_cli/`. +- Put library code under `src/zb_mom_ww_mxgateway/`. +- Put CLI entry points under `src/zb_mom_ww_mxgateway_cli/`. - Keep generated protobuf modules under a clearly named `generated` package. - Avoid import side effects that open channels, read environment variables, or start background tasks.