Joseph Doherty
84 lines
2.7 KiB
Markdown
84 lines
2.7 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.
|
|
|
|
## 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.
|