mxaccessgw/AGENTS.md

MXAccess Gateway Agent Guide

Repository: https://gitea.dohertylan.com/dohertj2/mxaccessgw

This project builds a gateway that gives modern clients full MXAccess parity without requiring those clients to load MXAccess COM, run as x86, or own an STA message pump. Treat the installed MXAccess COM component as the compatibility baseline.

Core Contract

Preserve MXAccess behavior first:

• public MXAccess command semantics,
• native MXAccess event families,
• STA/message-pump delivery behavior,
• installed-provider quirks,
• HRESULT/status/value marshaling,
• per-client isolation.

Do not simplify, normalize, or "fix" MXAccess behavior unless an explicit non-parity mode is being implemented and tested. MxAsbClient and managed NMX are future acceleration paths only; they do not define the parity contract.

Architecture

The intended split is:

client
  -> gRPC over TCP
    -> .NET 10 x64 gateway
      -> session manager
        -> per-session .NET Framework 4.8 x86 worker process
          -> dedicated STA thread
            -> MXAccess COM instance
            -> Windows/COM message pump
            -> command queue
            -> event sink

The gateway must never instantiate or call MXAccess directly. All MXAccess COM interaction belongs in the worker process on its dedicated STA thread.

The worker must not host public gRPC. Gateway-to-worker communication should use a small local IPC protocol, with named pipes and protobuf-framed messages as the default design.

Runtime Targets

• Gateway: .NET 10, C#, x64 preferred, ASP.NET Core gRPC.
• Worker: .NET Framework 4.8, C#, x86 by default.
• Worker IPC: one bidirectional named pipe per worker.
• Worker process model: one external client session maps to one worker by default.

Expected Layout

Prefer this structure unless there is a strong reason to adjust it:

src/MxGateway.Contracts/
  Protos/
    mxaccess_gateway.proto
    mxaccess_worker.proto
  Generated/

src/MxGateway.Server/
  Program.cs
  Sessions/
  Workers/
  Grpc/
  Metrics/

src/MxGateway.Worker/
  Program.cs
  Ipc/
  Sta/
  MxAccess/
  Conversion/

src/MxGateway.Tests/
  contract tests
  gateway session tests
  fake worker tests

src/MxGateway.Worker.Tests/
  value/status conversion tests
  STA queue tests

src/MxGateway.IntegrationTests/
  optional live MXAccess tests

The contracts project may multi-target, or the .proto files may be shared as source inputs to both gateway and worker builds.

Public API Shape

The external API should be session-oriented. Initial rollout should prefer unary OpenSession, CloseSession, and Invoke, plus server-streaming StreamEvents. Add a bidirectional Session stream after the command and event model is stable.

Do not compress MXAccess into generic verbs too early. Use a command enum with method-specific payloads so parity can be tested method by method.

Core MXAccess commands to represent:

• Register
• Unregister
• AddItem
• AddItem2
• RemoveItem
• Advise
• UnAdvise
• AdviseSupervisory
• AddBufferedItem
• SetBufferedUpdateInterval
• Suspend
• Activate
• Write
• Write2
• WriteSecured
• WriteSecured2
• AuthenticateUser
• ArchestrAUserToId

Diagnostics may include Ping, GetSessionState, GetWorkerInfo, DrainEvents, and ShutdownWorker.

Event Requirements

Represent every public MXAccess event family:

• OnDataChange
• OnWriteComplete
• OperationComplete
• OnBufferedDataChange

Preserve per-worker event order. The gateway must not reorder events emitted by the same MXAccess instance.

Event DTOs should carry event family, session id, server handle, item handle, value, quality, timestamp, MXSTATUS_PROXY[] equivalent, raw HRESULT/status fields when available, event sequence, worker timestamp, and gateway receive timestamp.

Value And Status Rules

Use a protobuf value union that can represent COM VARIANT values and arrays. When a value cannot be losslessly converted, preserve both the best typed projection and enough raw diagnostic metadata to reproduce the case.

Represent MXSTATUS_PROXY explicitly. Do not collapse status arrays into a single success flag.

Command replies should include protocol status, COM HRESULT if available, MXAccess return values, method-specific out parameters, and status arrays where the MXAccess method emits them.

Worker Rules

Each worker owns:

• one process,
• one MXAccess session,
• one dedicated STA thread,
• one MXAccess COM object,
• one inbound command queue,
• one outbound event queue.

All MXAccess operations must run on the STA. A plain blocking queue is not enough for the STA; the STA loop must pump Windows/COM messages and service queued commands.

Do not block the STA on pipe writes, gRPC calls, or slow consumers. Event handlers should convert event args, enqueue outbound events, and return to pumping messages.

On graceful shutdown, reject new commands, optionally clean up active MXAccess handles, detach events, release the COM object, uninitialize COM, and exit. If graceful shutdown exceeds the configured timeout, the gateway may kill the worker.

IPC Rules

Default pipe name shape:

mxaccess-gateway-{gatewayProcessId}-{sessionId}

Frame messages as:

uint32 little-endian payload_length
payload_length bytes protobuf WorkerEnvelope

Every envelope should include protocol version, session id, monotonic sender sequence, correlation id, and a typed body. Protocol version mismatch should fail session creation.

Pipe security should be local-machine only, with ACLs restricted to the gateway identity and launched worker identity. Prefer a per-session nonce handshake.

Gateway Rules

The gateway is responsible for:

• public TCP/gRPC API,
• authn/authz when needed,
• session creation and teardown,
• worker launch and lifecycle management,
• command routing,
• event streaming,
• leases, heartbeats, timeouts, and quotas,
• worker kill/restart policy,
• metrics and structured logs.

The gRPC layer should stay thin: validate request, find session, call the session worker client, map worker replies to public replies, and stream events. Keep MXAccess-specific translation logic testable outside the gRPC handlers.

Gateway restart should not try to reattach old workers in the first version. Terminate orphaned workers on startup if that behavior is implemented.

Command, Timeout, And Cancellation Semantics

Command lifecycle:

client gRPC command
gateway validates session and payload
gateway assigns correlation id
gateway writes WorkerCommand to pipe
worker queues command to STA
STA executes MXAccess method
worker captures return/out/status/HRESULT
worker sends WorkerCommandReply
gateway completes gRPC response

Canceling a gRPC call should stop waiting in the gateway, but it cannot safely abort an in-flight COM call on the STA. Hard cancellation means killing the worker process.

If a command wedges the STA beyond a configured grace period, the gateway should kill the worker and fail the session.

Backpressure Policy

Worker outbound events must use a bounded queue. For parity testing, prefer fail-fast behavior over silent drops. Production coalescing or drop policies must be explicit and observable.

The gateway should preserve per-session event order, apply backpressure from slow gRPC streams, and disconnect or coalesce only according to an explicit policy.

Security And Logging

Use TLS for remote gRPC when crossing machine boundaries. Authentication may be Windows auth, mTLS, or a deployment-specific token.

Commands that write, authenticate users, or alter runtime state need explicit authorization design.

Never log passwords or raw credential values for AuthenticateUser, WriteSecured, or related secured operations. Do not log full values by default; make value logging opt-in and redacted.

Testing Expectations

Use focused tests for:

• contract/protobuf compatibility,
• gateway session state and worker lifecycle,
• gateway behavior with a fake worker,
• worker value/status conversion,
• STA queue and message-pump behavior.

Live MXAccess integration tests are optional but should be isolated because they depend on installed COM components and provider behavior.

Parity tests should compare direct MXAccess behavior against the gateway:

• return values,
• HRESULTs and exceptions,
• event sequence,
• value projection,
• quality/status arrays,
• invalid handle behavior,
• cross-server handle behavior,
• cleanup behavior.

Known important parity areas:

• WriteSecured may fail before a value-bearing NMX body is emitted.
• WriteSecured2 can succeed in observed native paths.
• OperationComplete is distinct from write completion.
• OnBufferedDataChange has a distinct public event shape.
• Invalid handles and cross-server handles have specific exception/status behavior.
• STA message pumping is required for event delivery.

Implementation Priority

Build the smallest end-to-end slice first:

1. .NET 10 gateway starts.
2. Client calls OpenSession.
3. Gateway launches .NET Framework 4.8 x86 worker.
4. Worker creates STA and MXAccess COM object.
5. Client calls Register.
6. Client calls AddItem.
7. Client calls Advise.
8. Worker forwards one OnDataChange event to the gateway.
9. Gateway streams the event to the client.
10. Client calls CloseSession.
11. Gateway shuts down the worker.

That slice proves the high-risk requirements: process isolation, STA ownership, message pumping, command routing, and event streaming.