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>
397 lines
8.9 KiB
Markdown
397 lines
8.9 KiB
Markdown
# 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/ClientLibrariesDesign.md`
|
|
- `clients/dotnet/DotnetClientDesign.md`
|
|
- `clients/go/GoClientDesign.md`
|
|
- `clients/rust/RustClientDesign.md`
|
|
- `clients/python/PythonClientDesign.md`
|
|
- `clients/java/JavaClientDesign.md`
|
|
- `docs/ToolchainLinks.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/ToolchainLinks.md`,
|
|
- generated code command is documented for every language.
|
|
|
|
|
|
## Related Documentation
|
|
|
|
- [Implementation Plan Index](./ImplementationPlanIndex.md)
|
|
- [Client Libraries Detailed Design](./ClientLibrariesDesign.md)
|
|
- [Client Proto Generation](./ClientProtoGeneration.md)
|
|
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
|
- [Client Packaging](./ClientPackaging.md)
|
|
- [Cross-Language Smoke Matrix](./CrossLanguageSmokeMatrix.md)
|