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>
261 lines
8.1 KiB
Markdown
261 lines
8.1 KiB
Markdown
# Client Packaging
|
|
|
|
This document defines the clean-checkout commands for building, packaging, and
|
|
running the official MXAccess Gateway clients. Use the tool paths and versions
|
|
in [Toolchain Links](./ToolchainLinks.md) when a command is missing from
|
|
`PATH`.
|
|
|
|
## Shared Inputs
|
|
|
|
All clients generate bindings from the shared protobuf files under
|
|
`src/MxGateway.Contracts/Protos`. Regenerate the published client descriptor
|
|
after changing either `.proto` file or `clients/proto/proto-inputs.json`:
|
|
|
|
```powershell
|
|
scripts/publish-client-proto-inputs.ps1
|
|
scripts/publish-client-proto-inputs.ps1 -Check
|
|
```
|
|
|
|
Generated protobuf and gRPC files are generator output. Do not edit them by
|
|
hand.
|
|
|
|
## Environment
|
|
|
|
The examples use these common variables:
|
|
|
|
```powershell
|
|
$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
|
|
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
|
|
$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
|
|
```
|
|
|
|
Use plaintext only for a local gateway. Use TLS when the gateway crosses a
|
|
machine boundary or uses a production certificate.
|
|
|
|
## .NET
|
|
|
|
The .NET client uses .NET 10 and references
|
|
`src/MxGateway.Contracts/MxGateway.Contracts.csproj` for generated C# contract
|
|
types. `clients/dotnet/generated` remains reserved for client-local generator
|
|
output if the client later decouples from the contracts project.
|
|
|
|
Regenerate the generated C# contract types:
|
|
|
|
```powershell
|
|
dotnet build src/MxGateway.Contracts/MxGateway.Contracts.csproj
|
|
```
|
|
|
|
Build and test from the repository root:
|
|
|
|
```powershell
|
|
dotnet build clients/dotnet/MxGateway.Client.sln
|
|
dotnet test clients/dotnet/MxGateway.Client.sln --no-build
|
|
```
|
|
|
|
Create local package artifacts:
|
|
|
|
```powershell
|
|
$dotnetPackageOutput = Join-Path (Get-Location) 'artifacts/clients/dotnet'
|
|
dotnet pack clients/dotnet/MxGateway.Client/MxGateway.Client.csproj -c Release -p:PackageOutputPath="$dotnetPackageOutput"
|
|
dotnet publish clients/dotnet/MxGateway.Client.Cli/MxGateway.Client.Cli.csproj -c Release -o artifacts/clients/dotnet/mxgw-dotnet
|
|
```
|
|
|
|
Run the CLI from source:
|
|
|
|
```powershell
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- version --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint "http://$env:MXGATEWAY_ENDPOINT" --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
dotnet run --project clients/dotnet/MxGateway.Client.Cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
```
|
|
|
|
## Go
|
|
|
|
The Go client is the module
|
|
`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go`.
|
|
Generated Go files live under `clients/go/internal/generated`.
|
|
|
|
Regenerate the Go bindings:
|
|
|
|
```powershell
|
|
Push-Location clients/go
|
|
./generate-proto.ps1
|
|
Pop-Location
|
|
```
|
|
|
|
Build and test from `clients/go`:
|
|
|
|
```powershell
|
|
Push-Location clients/go
|
|
go test ./...
|
|
go build ./...
|
|
go vet ./...
|
|
Pop-Location
|
|
```
|
|
|
|
Create a local CLI executable:
|
|
|
|
```powershell
|
|
Push-Location clients/go
|
|
New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
|
|
go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
|
|
Pop-Location
|
|
```
|
|
|
|
Run the CLI from source:
|
|
|
|
```powershell
|
|
Push-Location clients/go
|
|
go run ./cmd/mxgw-go version -json
|
|
go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
|
|
go run ./cmd/mxgw-go smoke -endpoint mxgateway.example.local:5001 -ca-cert C:\certs\mxgateway-ca.pem -server-name-override mxgateway.example.local -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
|
|
Pop-Location
|
|
```
|
|
|
|
## Rust
|
|
|
|
The Rust workspace builds the `mxgateway-client` library crate and the `mxgw`
|
|
CLI crate. `build.rs` generates `tonic` and `prost` modules into Cargo build
|
|
output on each build that needs updated protobuf output.
|
|
|
|
Regenerate and compile Rust bindings:
|
|
|
|
```powershell
|
|
Push-Location clients/rust
|
|
cargo check --workspace
|
|
Pop-Location
|
|
```
|
|
|
|
Build and test from `clients/rust`:
|
|
|
|
```powershell
|
|
Push-Location clients/rust
|
|
cargo fmt --all --check
|
|
cargo test --workspace
|
|
cargo check --workspace
|
|
Pop-Location
|
|
```
|
|
|
|
Create local release artifacts:
|
|
|
|
```powershell
|
|
Push-Location clients/rust
|
|
cargo build --workspace --release
|
|
cargo install --path crates/mxgw-cli --locked --force
|
|
Pop-Location
|
|
```
|
|
|
|
Run the CLI from source:
|
|
|
|
```powershell
|
|
Push-Location clients/rust
|
|
cargo run -p mxgw-cli -- version --json
|
|
cargo run -p mxgw-cli -- smoke --endpoint "http://127.0.0.1:5000" --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
cargo run -p mxgw-cli -- smoke --endpoint "https://mxgateway.example.local:5001" --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
Pop-Location
|
|
```
|
|
|
|
## Python
|
|
|
|
The Python package is `mxaccess-gateway-client`. Generated modules live under
|
|
`clients/python/src/mxgateway/generated`.
|
|
|
|
Regenerate the Python bindings:
|
|
|
|
```powershell
|
|
Push-Location clients/python
|
|
./generate-proto.ps1
|
|
Pop-Location
|
|
```
|
|
|
|
Install, test, and build a wheel from `clients/python`:
|
|
|
|
```powershell
|
|
Push-Location clients/python
|
|
python -m pip install -e ".[dev]"
|
|
python -m pytest
|
|
python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
|
|
Pop-Location
|
|
```
|
|
|
|
Run the CLI from the editable install or with `python -m`:
|
|
|
|
```powershell
|
|
Push-Location clients/python
|
|
mxgw-py version --json
|
|
mxgw-py smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
mxgw-py smoke --endpoint mxgateway.example.local:5001 --tls --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json
|
|
python -m mxgateway_cli version --json
|
|
Pop-Location
|
|
```
|
|
|
|
## Java
|
|
|
|
The Java workspace uses Gradle, Java 21, `mxgateway-client`, and
|
|
`mxgateway-cli`. The Gradle protobuf plugin writes generated Java protobuf and
|
|
gRPC sources under `clients/java/src/main/generated`.
|
|
|
|
Regenerate Java bindings:
|
|
|
|
```powershell
|
|
Push-Location clients/java
|
|
gradle :mxgateway-client:generateProto
|
|
Pop-Location
|
|
```
|
|
|
|
Build and test from `clients/java`:
|
|
|
|
```powershell
|
|
Push-Location clients/java
|
|
gradle test
|
|
Pop-Location
|
|
```
|
|
|
|
Create local library and CLI artifacts:
|
|
|
|
```powershell
|
|
Push-Location clients/java
|
|
gradle :mxgateway-client:jar :mxgateway-cli:installDist
|
|
Pop-Location
|
|
```
|
|
|
|
Run the CLI through Gradle:
|
|
|
|
```powershell
|
|
Push-Location clients/java
|
|
gradle :mxgateway-cli:run --args="version --json"
|
|
gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
|
|
gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"
|
|
Pop-Location
|
|
```
|
|
|
|
## Integration Tests
|
|
|
|
Client integration checks are opt-in because they need a live gateway and a
|
|
gateway host that can create MXAccess worker sessions. Set the common
|
|
environment before running a client smoke:
|
|
|
|
```powershell
|
|
$env:MXGATEWAY_INTEGRATION = '1'
|
|
$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
|
|
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
|
|
$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
|
|
$env:MXGATEWAY_TEST_CONTEXT = ''
|
|
$env:MXGATEWAY_TEST_WRITE_VALUE = '123'
|
|
```
|
|
|
|
Run the bounded `smoke` command for each client against the same item. The
|
|
smoke commands open a session, register a client name, add one item, advise it,
|
|
and close the session. The .NET and Python smoke commands also read a bounded
|
|
event stream; the Go, Rust, and Java smoke commands exercise the command path
|
|
and can be paired with their `stream-events` commands after a session is open.
|
|
|
|
Client-side cancellation or timeout stops waiting for the gateway response. It
|
|
does not abort an MXAccess COM call that is already executing on the worker STA.
|
|
|
|
## Related Documentation
|
|
|
|
- [Client Proto Generation](./ClientProtoGeneration.md)
|
|
- [Client Libraries Detailed Design](./ClientLibrariesDesign.md)
|
|
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
|
- [Toolchain Links](./ToolchainLinks.md)
|