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.