Henara.Imaging.Contracts

Henara.Imaging proto contract.

protos/gateway.proto defines henara.imaging.v1: the DocumentRouter service, the page request and outcome messages, and the PageSide enum. Compiles DocumentRouter service and publishes the NuGet package.

Two repositories consume it, and neither compiles the .proto itself:

That is the whole point of the split. Before it, the client project reached sideways into the gateway checkout with a relative path, which worked only when both repositories sat next to each other on disk and broke a standalone clone.

Why a compiled package rather than shipping the .proto

Shipping the file would let each consumer compile it with its own GrpcServices setting, but it produces two distinct CLR types for every message — identical on the wire, not assignable to each other in C#. That costs nothing until something tries to hand a PageOutcome from one assembly to another, and then it is confusing out of all proportion to the problem.

GrpcServices="Both" means one package carries both halves. A consumer references the half it needs and ignores the other.

Changing the contract

The contract is the thing two deployables agree on, so a change here is a release, not an edit.

• Adding a message, an RPC, or a field with a new number is backwards compatible. Bump the minor version.
• Renaming a message is safe on the wire — proto3 binary carries field numbers, and only package + service + method form the gRPC method path — but it is a source-breaking change for both consumers. Bump the major version.
• Changing the package line, a service name, or an RPC name breaks the wire. An old client calling a renamed method gets RpcException/Unimplemented rather than anything diagnosable. Bump the major version and deploy the gateway before any client that expects the new name.
• Reusing a field number for a different type is the one genuinely dangerous edit. Don't; reserve the number instead.

Enums deserve particular care: proto3 cannot distinguish an unset enum field from its zero value. PageSide therefore keeps PAGE_SIDE_UNSPECIFIED = 0 so "we do not know which side this is" is representable. A contract whose zero value is a real, meaningful case silently reports that case for every page a sender forgot to fill in.

Build

dotnet pack src/Henara.Imaging.Contracts/Henara.Imaging.Contracts.csproj -c Release -o nupkg

Targets net8.0, net9.0 and net10.0. The gateway is pinned to net10.0 by Henara.Scan.Client, but Henara.Imaging.Client goes back to net8.0, and the contract must not be the thing that forces a caller forward.

Release order

The two consumers restore this package from the feed, so it has to be there first:

1. Tag and publish Henara.Imaging.Contracts.
2. Bump the PackageReference in the gateway, build, deploy.
3. Bump the PackageReference in the client, build, publish.

For local work across all three without publishing, point a nuget.config at this repository's nupkg/ output directory as an additional source.