mxaccessgw/docs/implementation-plan-clients.md

Client Libraries Implementation Plan

This plan implements the official gRPC clients after the gateway and worker first slice is stable enough to generate contracts and run smoke tests.

Primary designs:

• docs/client-libraries-design.md
• docs/clients-dotnet-csharp-design.md
• docs/clients-golang-design.md
• docs/clients-rust-design.md
• docs/clients-python-design.md
• docs/clients-java-design.md
• docs/toolchain-links.md

Shared Milestone: client-contracts-and-fixtures

Goal: make client implementations consistent across languages.

Issue: Publish Stable Client Proto Generation Inputs

Labels: area:contracts, type:feature, priority:p0

Deliverables:

• finalized v1 .proto files,
• Buf config if used,
• generation documentation for all languages,
• generated-code output directories,
• golden protobuf payload fixtures.

Acceptance criteria:

• C#, Go, Rust, Python, and Java generated code can be regenerated,
• generated code is not hand-edited,
• protocol version is visible to clients.

Issue: Create Cross-Language Client Behavior Fixtures

Labels: area:tests, type:test, priority:p0

Deliverables:

• JSON fixtures for command replies,
• JSON fixtures for event stream samples,
• value conversion fixtures,
• status conversion fixtures,
• auth error fixtures,
• timeout/cancel expected behavior notes.

Acceptance criteria:

• every language can use the same fixture set,
• fixtures include raw fallback values,
• fixtures include MXAccess status arrays and HRESULT.

Milestone: clients-dotnet

Goal: implement the .NET 10 C# client library, test CLI, and tests.

Issue: Scaffold .NET Client Projects

Labels: area:client-dotnet, type:infra, priority:p0

Deliverables:

• clients/dotnet/MxGateway.Client,
• clients/dotnet/MxGateway.Client.Cli,
• clients/dotnet/MxGateway.Client.Tests,
• optional integration test project,
• generated protobuf setup.

Acceptance criteria:

• dotnet build succeeds,
• generated gRPC client code compiles,
• empty tests run.

Issue: Implement .NET GatewayClient And Session

Labels: area:client-dotnet, type:feature, priority:p0

Deliverables:

• MxGatewayClientOptions,
• MxGatewayClient,
• MxGatewaySession,
• raw OpenSession, CloseSession, Invoke, StreamEvents,
• helpers for Register, AddItem, AddItem2, Advise, Write.

Acceptance criteria:

• API key metadata is attached,
• cancellation token flows to every call,
• raw replies remain accessible,
• session close is explicit and idempotent.

Tests:

• fake gRPC service,
• helper request construction,
• cancellation.

Issue: Implement .NET Values, Status, Errors, And CLI

Labels: area:client-dotnet, type:feature, priority:p1

Deliverables:

• MxValue helper conversions,
• status proxy helpers,
• typed exceptions,
• EnsureProtocolSuccess,
• EnsureMxAccessSuccess,
• CLI commands: version, ping, open-session, close-session, register, add-item, advise, stream-events, write, write2, smoke,
• JSON CLI output.

Acceptance criteria:

• scalar and array conversions pass fixtures,
• status arrays are preserved,
• API keys are redacted,
• smoke command closes session in finally.

Milestone: clients-go

Goal: implement the Go module, test CLI, and tests.

Issue: Scaffold Go Module

Labels: area:client-go, type:infra, priority:p0

Deliverables:

• clients/go/go.mod,
• generated protobuf package,
• mxgateway package,
• cmd/mxgw-go,
• unit test structure.

Acceptance criteria:

• go test ./... runs,
• generated code compiles,
• module path is stable.

Issue: Implement Go Client, Session, Values, Errors, And CLI

Labels: area:client-go, type:feature, priority:p0

Deliverables:

• Dial(ctx, Options),
• auth interceptors,
• TLS/plaintext setup,
• Client.OpenSession,
• Session helpers,
• event channel receive loop,
• value conversion helpers,
• typed errors with errors.As,
• CLI commands and JSON output.

Acceptance criteria:

• auth metadata on unary and streams,
• context cancellation stops calls,
• event channel closes exactly once,
• raw protobuf access remains available,
• fixture conversions pass,
• CLI redacts API key.

Tests:

• bufconn fake service,
• auth metadata,
• stream cancellation,
• conversion fixtures,
• CLI parser/output.

Milestone: clients-rust

Goal: implement the Rust tonic client crate, test CLI, and tests.

Issue: Scaffold Rust Workspace

Labels: area:client-rust, type:infra, priority:p0

Deliverables:

• clients/rust/Cargo.toml,
• client crate,
• CLI crate,
• build.rs protobuf generation,
• generated module organization.

Acceptance criteria:

• cargo test runs,
• generated code compiles,
• MSVC linker works.

Issue: Implement Rust Client, Session, Values, Errors, And CLI

Labels: area:client-rust, type:feature, priority:p0

Deliverables:

• ClientOptions,
• GatewayClient::connect,
• auth interceptor,
• TLS/plaintext channel,
• session helpers,
• event stream as Stream<Item = Result<MxEvent, Error>>,
• thiserror error model,
• conversion helpers,
• clap CLI,
• JSON output with serde_json.

Acceptance criteria:

• metadata includes bearer key,
• dropped stream cancels underlying stream,
• raw generated client remains reachable where needed,
• fixture tests pass,
• command errors keep raw reply,
• API key is redacted from debug output.

Tests:

• fake tonic server,
• auth tests,
• stream order/cancel,
• conversion fixtures,
• CLI parser/output.

Milestone: clients-python

Goal: implement the async Python client package, test CLI, and tests.

Issue: Scaffold Python Package

Labels: area:client-python, type:infra, priority:p0

Deliverables:

• clients/python/pyproject.toml,
• src/mxgateway,
• generated protobuf modules,
• src/mxgateway_cli,
• tests.

Acceptance criteria:

• package installs editable,
• generated stubs import,
• pytest runs.

Issue: Implement Python Async Client, Values, Errors, And CLI

Labels: area:client-python, type:feature, priority:p0

Deliverables:

• async GatewayClient,
• async Session,
• auth metadata helper,
• TLS/plaintext setup,
• async event iterator,
• method helpers,
• value conversion helpers,
• typed exceptions,
• click or typer CLI,
• JSON output.

Acceptance criteria:

• API key metadata included,
• async cancellation cancels stream/call,
• raw protobuf replies available,
• fixture conversions pass,
• secrets redacted.

Tests:

• fake async stub tests,
• metadata tests,
• cancellation tests,
• conversion fixtures,
• CLI parser/output.

Milestone: clients-java

Goal: implement Java client library, CLI, and tests.

Issue: Scaffold Java Gradle Build

Labels: area:client-java, type:infra, priority:p0

Deliverables:

• clients/java/settings.gradle,
• mxgateway-client project,
• mxgateway-cli project,
• protobuf/gRPC Gradle generation,
• JUnit test setup.

Acceptance criteria:

• gradle test runs,
• generated code compiles,
• Java 21 toolchain used.

Issue: Implement Java Client, Session, Values, Errors, And CLI

Labels: area:client-java, type:feature, priority:p0

Deliverables:

• MxGatewayClientOptions,
• MxGatewayClient,
• MxGatewaySession,
• auth interceptor,
• plaintext/TLS channels,
• blocking and async event stream options,
• method helpers,
• value conversion helpers,
• typed exceptions,
• picocli CLI,
• JSON output.

Acceptance criteria:

• unary and streaming calls carry auth metadata,
• deadlines are applied,
• stream cancellation works,
• raw generated messages are accessible,
• fixture tests pass,
• CLI redacts secrets.

Tests:

• in-process gRPC tests,
• auth interceptor,
• stream cancellation,
• conversion fixtures,
• CLI parser/output.

Milestone: integration-and-parity

Goal: prove clients can talk to the gateway consistently.

Issue: Cross-Language Smoke Test Matrix

Labels: area:tests, type:test, priority:p1

Deliverables:

• common smoke script or documented commands,
• each client runs open/register/add/advise/stream/close,
• JSON output comparison,
• optional write test.

Acceptance criteria:

• each client has equivalent smoke behavior,
• each client skips integration unless MXGATEWAY_INTEGRATION=1,
• failed smoke output includes endpoint, language, and redacted auth context.

Issue: Client Packaging Documentation

Labels: area:docs, type:docs, priority:p2

Deliverables:

• install instructions per client,
• generation instructions,
• CLI usage examples,
• TLS/API key examples,
• integration test instructions.

Acceptance criteria:

• new developer can build each client from a clean checkout using docs/toolchain-links.md,
• generated code command is documented for every language.