# 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)
