Joseph Doherty
51a9dadf62
- Rename 16 kebab-case docs to PascalCase per StyleGuide - Move per-language client design docs from docs/ to clients/<lang>/ alongside their READMEs - Add ## Related Documentation sections to 15 docs that lacked one - Fix sentence-case violations in H3 headings (StyleGuide rule) - Update cross-references in gateway.md, client READMEs, scripts, and generate-proto.ps1 helpers to follow the new paths - Add CLAUDE.md with build/test commands, the source-update verification matrix, the parity-first contract, and pointers to MXAccess and Galaxy Repository analysis sources Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3.0 KiB
Protobuf Contracts
The contracts project contains the public gRPC API and the gateway-to-worker
IPC messages. The .proto files are the source of truth; generated C# files are
recreated by the contracts project build.
Files
src/MxGateway.Contracts/Protos/mxaccess_gateway.proto defines the public
MxAccessGateway gRPC service, command payloads, command replies, event DTOs,
MxValue, MxArray, and MxStatusProxy.
The public command model includes bulk subscription command kinds for
AddItemBulk, AdviseItemBulk, RemoveItemBulk, UnAdviseItemBulk,
SubscribeBulk, and UnsubscribeBulk. These commands are normal unary
Invoke payloads. They do not add separate gRPC methods, and they return a
BulkSubscribeReply containing per-item SubscribeResult records with
ServerHandle, TagAddress, ItemHandle, WasSuccessful, and
ErrorMessage.
The gateway forwards each bulk command as one worker command. The worker runs
the corresponding MXAccess AddItem, Advise, UnAdvise, and RemoveItem
calls sequentially on the session STA and preserves input order in the result
list.
src/MxGateway.Contracts/Protos/mxaccess_worker.proto defines the named-pipe
worker IPC envelope and control messages. It imports
mxaccess_gateway.proto so the worker and gateway use the same command, reply,
event, value, and status shapes.
src/MxGateway.Contracts/Protos/galaxy_repository.proto defines the
GalaxyRepository service used by clients to browse the Galaxy Repository
(deployed object hierarchy and dynamic attributes). The service is metadata-
only and does not share types with mxaccess_gateway.proto. See
Galaxy Repository Browse for the RPC catalog and
behavior.
Generated C# output is written to src/MxGateway.Contracts/Generated/. Do not
hand-edit generated files.
Client generation inputs are published through
clients/proto/proto-inputs.json and the descriptor set under
clients/proto/descriptors/. See
Client Proto Generation for language-specific
generation inputs, output directories, and golden protobuf JSON fixtures.
Generation
Run the contracts build to regenerate C# protobuf and gRPC code:
dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
Run the focused contract tests after changing either .proto file:
dotnet test src/MxGateway.Tests/MxGateway.Tests.csproj --filter ProtobufContractRoundTripTests
The full solution build also regenerates the C# contracts before compiling gateway and test projects:
dotnet build src/MxGateway.sln
Regenerate the client descriptor after changing either .proto file:
powershell -ExecutionPolicy Bypass -File scripts/publish-client-proto-inputs.ps1