Joseph Doherty
126 lines
4.0 KiB
Markdown
126 lines
4.0 KiB
Markdown
# Go Client
|
|
|
|
The Go client module contains the generated MXAccess Gateway protobuf bindings,
|
|
a small handwritten `mxgateway` package, and the `mxgw-go` test CLI scaffold.
|
|
The module uses the shared proto inputs documented in
|
|
`../../docs/client-proto-generation.md` so gateway and client contracts stay in
|
|
sync.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
clients/go/
|
|
go.mod
|
|
generate-proto.ps1
|
|
internal/generated/
|
|
mxgateway/
|
|
cmd/mxgw-go/
|
|
```
|
|
|
|
`internal/generated` contains code produced by `protoc`, `protoc-gen-go`, and
|
|
`protoc-gen-go-grpc`. Do not edit generated files by hand.
|
|
|
|
## Regenerating Protobuf Bindings
|
|
|
|
Run generation after the shared `.proto` files or the Go output path changes:
|
|
|
|
```powershell
|
|
./generate-proto.ps1
|
|
```
|
|
|
|
The script uses the tool paths recorded in `../../docs/toolchain-links.md`.
|
|
|
|
## Build And Test
|
|
|
|
Run the Go module checks from `clients/go`:
|
|
|
|
```powershell
|
|
go test ./...
|
|
go build ./...
|
|
go vet ./...
|
|
```
|
|
|
|
The tests parse the shared JSON fixtures, exercise value and status conversion,
|
|
use `bufconn` for fake gateway auth and streaming behavior, and cover CLI JSON
|
|
redaction.
|
|
|
|
## Packaging
|
|
|
|
Build a local CLI executable from `clients/go`:
|
|
|
|
```powershell
|
|
New-Item -ItemType Directory -Force ../../artifacts/clients/go | Out-Null
|
|
go build -o ../../artifacts/clients/go/mxgw-go.exe ./cmd/mxgw-go
|
|
```
|
|
|
|
Install the CLI into the active `GOBIN` or `GOPATH/bin`:
|
|
|
|
```powershell
|
|
go install ./cmd/mxgw-go
|
|
```
|
|
|
|
Other Go modules can consume the library package with the module path
|
|
`gitea.dohertylan.com/dohertj2/mxaccessgw/clients/go/mxgateway`.
|
|
|
|
## Client API
|
|
|
|
Use `mxgateway.Dial` with `mxgateway.Options` to configure plaintext or TLS
|
|
transport, API-key metadata, dial timeout, and per-call timeout:
|
|
|
|
```go
|
|
client, err := mxgateway.Dial(ctx, mxgateway.Options{
|
|
Endpoint: "localhost:5000",
|
|
APIKey: os.Getenv("MXGATEWAY_API_KEY"),
|
|
Plaintext: true,
|
|
})
|
|
```
|
|
|
|
`Client.OpenSession` returns a `Session` with helpers for `Register`,
|
|
`AddItem`, `AddItem2`, `Advise`, `Write`, `Events`, and `Close`. Raw protobuf
|
|
messages remain available through the `mxgateway` package aliases and the
|
|
`Raw` helper methods. Typed errors support `errors.As` for `GatewayError`,
|
|
`CommandError`, and `MxAccessError`; command errors preserve the raw reply.
|
|
|
|
## CLI
|
|
|
|
The `mxgw-go` CLI emits JSON with redacted API keys for commands that connect to
|
|
the gateway:
|
|
|
|
```powershell
|
|
go run ./cmd/mxgw-go version -json
|
|
go run ./cmd/mxgw-go open-session -endpoint localhost:5000 -plaintext -json
|
|
go run ./cmd/mxgw-go register -session-id <id> -client-name mxgw-go -plaintext -json
|
|
go run ./cmd/mxgw-go add-item -session-id <id> -server-handle 1 -item Area001.Tag.Value -plaintext -json
|
|
go run ./cmd/mxgw-go advise -session-id <id> -server-handle 1 -item-handle 1 -plaintext -json
|
|
go run ./cmd/mxgw-go write -session-id <id> -server-handle 1 -item-handle 1 -type int32 -value 123 -plaintext -json
|
|
go run ./cmd/mxgw-go stream-events -session-id <id> -plaintext -json
|
|
go run ./cmd/mxgw-go smoke -item Area001.Tag.Value -plaintext -json
|
|
```
|
|
|
|
Use `-api-key-env MXGATEWAY_API_KEY` or `-api-key <key>` when authentication is
|
|
enabled. CLI output redacts the key value and never writes the raw secret.
|
|
|
|
Use TLS options for a secured gateway:
|
|
|
|
```powershell
|
|
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 Area001.Tag.Value -json
|
|
```
|
|
|
|
## Integration Checks
|
|
|
|
Run live checks only when a gateway and MXAccess-backed worker are available:
|
|
|
|
```powershell
|
|
$env:MXGATEWAY_INTEGRATION = '1'
|
|
$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
|
|
$env:MXGATEWAY_API_KEY = '<gateway-api-key>'
|
|
$env:MXGATEWAY_TEST_ITEM = 'Area001.Tag.Value'
|
|
go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key-env MXGATEWAY_API_KEY -item $env:MXGATEWAY_TEST_ITEM -json
|
|
```
|
|
|
|
## Related Documentation
|
|
|
|
- [Client Packaging](../../docs/ClientPackaging.md)
|
|
- [Client Proto Generation](../../docs/client-proto-generation.md)
|
|
- [Go Client Detailed Design](../../docs/clients-golang-design.md)
|