Issue #2: define protobuf contracts

2026-04-26 16:10:11 -04:00
parent 16c18954b6
commit a462f68dbd
8 changed files with 23688 additions and 0 deletions
@@ -0,0 +1,46 @@
+# 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`.
+
+`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.
+
+Generated C# output is written to `src/MxGateway.Contracts/Generated/`. Do not
+hand-edit generated files.
+
+## Generation
+
+Run the contracts build to regenerate C# protobuf and gRPC code:
+
+```bash
+dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
+```
+
+Run the focused contract tests after changing either `.proto` file:
+
+```bash
+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:
+
+```bash
+dotnet build src/MxGateway.sln
+```
+
+## Related Documentation
+
+- [Gateway Process Detailed Design](./gateway-process-design.md)
+- [MXAccess Worker Instance Detailed Design](./mxaccess-worker-instance-design.md)
+- [Protobuf Style Guide](./style-guides/ProtobufStyleGuide.md)