Issue #50: document client packaging
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,260 @@
|
||||
# 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](./toolchain-links.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 = 'mxgw_key_id_secret'
|
||||
$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 = 'mxgw_key_id_secret'
|
||||
$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](./client-proto-generation.md)
|
||||
- [Client Libraries Detailed Design](./client-libraries-design.md)
|
||||
- [Client Behavior Fixtures](./ClientBehaviorFixtures.md)
|
||||
- [Toolchain Links](./toolchain-links.md)
|
||||
Reference in New Issue
Block a user