scadaproj/components/health/current-state/mxaccessgw/CURRENT-STATE.md

# Health — current state: MxAccessGateway

Repo: `~/Desktop/MxAccessGateway`. Stack: .NET 10 gateway (x64) + .NET 4.8 worker (x86), gRPC;
solution `src/MxGateway.sln`.
Health code lives in `src/ZB.MOM.WW.MxGateway.Server/GatewayApplication.cs`. All paths relative
to repo root.
Verified 2026-06-01.

**Summary: bare liveness only.** MxAccessGateway has a single `/health/live` endpoint that returns
a hardcoded `GatewayHealthReply` JSON object. `AddHealthChecks()` is called at startup but is
entirely unused — no `IHealthCheck` implementations are registered, `MapHealthChecks` is never
called, and there is no readiness or active-node tier. The net48 x86 worker process has no HTTP
server and therefore no health endpoint of any kind.

## 1. Endpoint wiring

`src/ZB.MOM.WW.MxGateway.Server/GatewayApplication.cs`:

- `:61` — `builder.Services.AddHealthChecks()` is called in the DI registration block. **This call
  is dead**: no `.AddCheck<T>()` call follows it, no `MapHealthChecks` is ever called. The
  framework registers the health-check infrastructure but nothing is wired through it.
- `:139–145` — `MapGatewayEndpoints` maps a raw `endpoints.MapGet("/health/live", ...)` (not
  `MapHealthChecks`). The handler is an inline lambda that returns `Results.Ok(new GatewayHealthReply(...))`
  with a hardcoded `Status: "Healthy"`:

  ```csharp
  endpoints.MapGet(
      "/health/live",
      () => Results.Ok(new GatewayHealthReply(
          Status: "Healthy",
          DefaultBackend: GatewayContractInfo.DefaultBackendName,
          WorkerProtocolVersion: GatewayContractInfo.WorkerProtocolVersion)))
      .WithName("LiveHealth");
  ```

This endpoint always returns HTTP 200 `{"Status":"Healthy",...}` as long as the process is alive.
It carries no authentication requirement (no `[Authorize]` or `.RequireAuthorization()`).

## 2. Response shape

`GatewayHealthReply` is a record with three fields:
- `Status` — always `"Healthy"` (hardcoded string, not the ASP.NET Core `HealthStatus` enum)
- `DefaultBackend` — value of `GatewayContractInfo.DefaultBackendName` (the configured backend
  name, useful for confirming which gateway instance a probe hit)
- `WorkerProtocolVersion` — value of `GatewayContractInfo.WorkerProtocolVersion` (the gRPC
  protocol version the gateway expects from the worker, useful for version-skew detection)

The response is not `HealthChecks.UI.Client` JSON and is not the standard ASP.NET Core health
response shape. It is a bespoke JSON record.

## 3. Probes

None. There is no `IHealthCheck` registered. The `/health/live` response does not reflect:

- Whether the SQLite auth-store is reachable
- Whether any active MXAccess session is functional
- Whether the x86 worker named-pipe IPC is connected or the worker process is alive
- Whether the gRPC service is actually accepting calls

The endpoint is purely a process liveness indicator.

## 4. Tier coverage

| Tier | Endpoint | Status |
|---|---|---|
| Process liveness | `/health/live` (raw `MapGet`) | ✅ present (but non-standard) |
| Readiness | `/health/ready` | ⛔ absent |
| Active node | `/health/active` | ⛔ absent (not Akka-based; not applicable as-is) |
| `healthz` convention | `/healthz` | ⛔ absent |

MxAccessGateway is not an Akka.NET application — it has no cluster, no leader election, and no
active-node concept. The "active" tier in the shared spec translates here to "is the worker process
connected and the gRPC service ready to accept calls?" rather than cluster leadership.

## 5. x86 worker

`ZB.MOM.WW.MxGateway.Worker` is a .NET 4.8 console application communicating with the gateway
over Windows named-pipe IPC. It has no HTTP server, no health endpoint, and no exposure to any
probe mechanism. Its liveness must be inferred indirectly — either via the gateway process
monitoring it (not currently implemented) or via the `GrpcDependencyHealthCheck` the gateway
could use to probe the IPC channel.

## 6. Notable gaps

- `AddHealthChecks()` at `:61` is dead code. No `IHealthCheck` is ever registered via this call.
- `/health/live` uses `MapGet` (a raw minimal-API handler) rather than `MapHealthChecks`. It
  bypasses the ASP.NET Core health-check middleware entirely, which means it does not participate
  in the standard health-check pipeline (no `IHealthCheckPublisher`, no `HealthReport`, no UI
  integration).
- The hardcoded `"Healthy"` status means the endpoint cannot reflect real probe results even if
  probes were added later — the handler must be replaced, not just supplemented.
- No readiness gating: orchestrators (Kubernetes, Traefik) that rely on `/health/ready` returning
  503 until the process is actually ready will receive 200 (or 404) from MxAccessGateway today.

---

## Adoption plan → `ZB.MOM.WW.Health`

**Replace `/health/live` + wire the shared tiers:**

The `AddHealthChecks()` call at `GatewayApplication.cs:61` is already present — it just needs
probes registered against it. The raw `MapGet("/health/live", ...)` handler at `:139–145` must be
removed and replaced with `app.MapZbHealth()` from `ZB.MOM.WW.Health`.

Steps:

1. **Remove** the inline `MapGet("/health/live", ...)` lambda (`:139–145`). The `GatewayHealthReply`
   record and `DefaultBackend`/`WorkerProtocolVersion` metadata can be surfaced differently (e.g., a
   `/info` endpoint or as custom data on the health response).
2. **Register a `GrpcDependencyHealthCheck`** (from `ZB.MOM.WW.Health`) that probes the
   named-pipe IPC channel to the x86 worker. Tag `["ready"]`. This replaces the hardcoded
   liveness-only response with a real probe that reflects whether the worker is reachable.
3. **Optionally add a `GrpcDependencyHealthCheck`** for any downstream gRPC dependency (e.g., the
   Galaxy Repository connection) if the gateway is expected to be healthy only when its upstreams are
   reachable. Tag `["ready"]`.
4. **Call `app.MapZbHealth()`** — this maps `/health/ready` (tag `ready`), `/health/active` (tag
   `active`; initially empty — no active-node concept in MxGateway), and `/healthz` (bare liveness).
   The `/healthz` endpoint replaces the semantic role that `/health/live` served today.
5. **Do not add `ZB.MOM.WW.Health.Akka`** — MxAccessGateway has no Akka dependency. The consumer
   matrix in the design specifies MxGateway uses the core package only.

**Keep bespoke:**

- The `WorkerProtocolVersion` / `DefaultBackend` metadata from `GatewayHealthReply` is
  MxAccessGateway-specific; keep it as a separate `/info` endpoint or embed it as `Data` on a
  custom probe rather than normalizing it into the shared contract.
- The x86 worker itself (net48 console, named-pipe IPC, no HTTP) remains outside the shared health
  scheme. The `GrpcDependencyHealthCheck` observes the worker indirectly from the gateway side.
- Per-gateway auth and TLS concerns on who may call health endpoints remain per-project.

**Adoption is a follow-on task** (tracked in `GAPS.md`), not part of the `ZB.MOM.WW.Health`
library build. MxGateway is the **highest-priority adopter** (P1 gap — no probes/tiers today)
and should be the first app wired up once the nupkg is available.