Add idiomatic documentation to Go, Java, Python, and Rust clients

This commit is contained in:
Joseph Doherty
2026-04-30 12:04:46 -04:00
parent eed1e88a37
commit 8d3352f2c6
44 changed files with 1631 additions and 102 deletions
+5
View File
@@ -1,3 +1,8 @@
// Command mxgw-go is the reference Go CLI for the MXAccess Gateway.
//
// It exposes versioning, session lifecycle, command invocation, event
// streaming, a smoke-test workflow, and Galaxy Repository browse subcommands
// that exercise the same gRPC contract used by the mxgateway library.
package main
import (
+19 -3
View File
@@ -1,3 +1,14 @@
// Package mxgateway is the Go client for the MXAccess Gateway gRPC service.
//
// The package wraps the generated gRPC contract with session-oriented helpers
// for invoking MXAccess commands, streaming events, and browsing the Galaxy
// Repository. Authentication uses an API-key bearer token attached as gRPC
// metadata on every call.
//
// Typical use opens a Client with Dial, opens a Session, invokes commands such
// as Register, AddItem, Advise, and Write, and consumes events via
// SubscribeEvents. Galaxy Repository browse RPCs are exposed through
// GalaxyClient.
package mxgateway
import (
@@ -219,10 +230,15 @@ func resolveTransportCredentials(opts Options) (credentials.TransportCredentials
// OpenSessionOptions describes fields used to create an OpenSessionRequest.
type OpenSessionOptions struct {
RequestedBackend string
ClientSessionName string
// RequestedBackend selects the gateway worker backend (empty for default).
RequestedBackend string
// ClientSessionName is a human-readable name recorded on the session.
ClientSessionName string
// ClientCorrelationID echoes through gateway logs and replies for tracing.
ClientCorrelationID string
CommandTimeout time.Duration
// CommandTimeout sets the per-command timeout the gateway forwards to the
// worker; zero leaves the gateway default in place.
CommandTimeout time.Duration
}
// Request returns the raw protobuf OpenSessionRequest for these options.
+16 -4
View File
@@ -8,10 +8,13 @@ import (
// GatewayError wraps transport-level gRPC failures.
type GatewayError struct {
Op string
// Op names the operation that failed (for example "dial" or "invoke").
Op string
// Err is the underlying gRPC or transport error.
Err error
}
// Error returns the formatted gateway error message.
func (e *GatewayError) Error() string {
if e == nil {
return ""
@@ -22,6 +25,7 @@ func (e *GatewayError) Error() string {
return fmt.Sprintf("mxgateway: %s failed: %v", e.Op, e.Err)
}
// Unwrap returns the wrapped transport error.
func (e *GatewayError) Unwrap() error {
if e == nil {
return nil
@@ -32,11 +36,15 @@ func (e *GatewayError) Unwrap() error {
// CommandError reports a non-OK gateway protocol status and keeps the raw
// command reply when one exists.
type CommandError struct {
Op string
// Op names the gateway operation that produced the non-OK status.
Op string
// Status carries the gateway-reported protocol status.
Status *ProtocolStatus
Reply *MxCommandReply
// Reply is the raw command reply, when one was returned alongside the status.
Reply *MxCommandReply
}
// Error returns the formatted command error message.
func (e *CommandError) Error() string {
if e == nil {
return ""
@@ -53,10 +61,13 @@ func (e *CommandError) Error() string {
// MxAccessError reports HRESULT or MXSTATUS_PROXY failures returned by MXAccess.
type MxAccessError struct {
// Command is the wrapped CommandError when the protocol status carried one.
Command *CommandError
Reply *MxCommandReply
// Reply is the raw MXAccess command reply that surfaced the failure.
Reply *MxCommandReply
}
// Error returns the formatted MXAccess error message.
func (e *MxAccessError) Error() string {
if e == nil {
return ""
@@ -73,6 +84,7 @@ func (e *MxAccessError) Error() string {
return "mxgateway: MXAccess command failed"
}
// Unwrap returns the wrapped CommandError, when one is present.
func (e *MxAccessError) Unwrap() error {
if e == nil {
return nil
+20 -10
View File
@@ -20,16 +20,26 @@ type RawGalaxyRepositoryClient = pb.GalaxyRepositoryClient
// Generated protobuf aliases for Galaxy Repository messages.
type (
TestConnectionRequest = pb.TestConnectionRequest
TestConnectionReply = pb.TestConnectionReply
GetLastDeployTimeRequest = pb.GetLastDeployTimeRequest
GetLastDeployTimeReply = pb.GetLastDeployTimeReply
DiscoverHierarchyRequest = pb.DiscoverHierarchyRequest
DiscoverHierarchyReply = pb.DiscoverHierarchyReply
GalaxyObject = pb.GalaxyObject
GalaxyAttribute = pb.GalaxyAttribute
WatchDeployEventsRequest = pb.WatchDeployEventsRequest
DeployEvent = pb.DeployEvent
// TestConnectionRequest is the request for Galaxy Repository TestConnection.
TestConnectionRequest = pb.TestConnectionRequest
// TestConnectionReply is the reply for Galaxy Repository TestConnection.
TestConnectionReply = pb.TestConnectionReply
// GetLastDeployTimeRequest is the request for GetLastDeployTime.
GetLastDeployTimeRequest = pb.GetLastDeployTimeRequest
// GetLastDeployTimeReply is the reply for GetLastDeployTime.
GetLastDeployTimeReply = pb.GetLastDeployTimeReply
// DiscoverHierarchyRequest is the request for DiscoverHierarchy.
DiscoverHierarchyRequest = pb.DiscoverHierarchyRequest
// DiscoverHierarchyReply is the reply for DiscoverHierarchy.
DiscoverHierarchyReply = pb.DiscoverHierarchyReply
// GalaxyObject describes one Galaxy object with its dynamic attributes.
GalaxyObject = pb.GalaxyObject
// GalaxyAttribute describes one dynamic attribute on a GalaxyObject.
GalaxyAttribute = pb.GalaxyAttribute
// WatchDeployEventsRequest is the request for WatchDeployEvents.
WatchDeployEventsRequest = pb.WatchDeployEventsRequest
// DeployEvent is one Galaxy Repository deploy event.
DeployEvent = pb.DeployEvent
)
// RawDeployEventStream is the generated WatchDeployEvents client stream.
+22 -9
View File
@@ -11,16 +11,29 @@ import (
// Options configures gateway connections.
type Options struct {
Endpoint string
APIKey string
Plaintext bool
CACertFile string
ServerNameOverride string
DialTimeout time.Duration
CallTimeout time.Duration
TLSConfig *tls.Config
// Endpoint is the gateway host:port address to dial.
Endpoint string
// APIKey is the bearer token attached to outgoing gRPC metadata.
APIKey string
// Plaintext disables TLS and uses insecure credentials when true.
Plaintext bool
// CACertFile points to a PEM file used to verify the gateway certificate.
CACertFile string
// ServerNameOverride overrides the TLS SNI/SAN name presented to the gateway.
ServerNameOverride string
// DialTimeout bounds the blocking Dial; zero applies a built-in default.
DialTimeout time.Duration
// CallTimeout bounds each unary RPC; zero applies a built-in default and
// negative disables the bound entirely.
CallTimeout time.Duration
// TLSConfig supplies a custom TLS configuration; takes precedence over
// CACertFile when TransportCredentials is unset.
TLSConfig *tls.Config
// TransportCredentials, when non-nil, overrides every other transport-level
// option and is used as-is.
TransportCredentials credentials.TransportCredentials
DialOptions []grpc.DialOption
// DialOptions are appended to the gRPC dial options after the defaults.
DialOptions []grpc.DialOption
}
// RedactedAPIKey returns a display-safe representation of the configured API
+3 -1
View File
@@ -18,8 +18,10 @@ const maxBulkItems = 1000
// EventResult carries either the next ordered event or a terminal stream error.
type EventResult struct {
// Event is the next event from the stream when Err is nil.
Event *MxEvent
Err error
// Err is the terminal stream error; when non-nil no further results follow.
Err error
}
// EventSubscription owns a running gateway event stream.
+126 -58
View File
@@ -12,77 +12,145 @@ type RawEventStream = pb.MxAccessGateway_StreamEventsClient
// Generated protobuf aliases keep raw contract access available from the public
// mxgateway package while generated code remains under internal/generated.
type (
OpenSessionRequest = pb.OpenSessionRequest
OpenSessionReply = pb.OpenSessionReply
CloseSessionRequest = pb.CloseSessionRequest
CloseSessionReply = pb.CloseSessionReply
StreamEventsRequest = pb.StreamEventsRequest
MxCommandRequest = pb.MxCommandRequest
MxCommandReply = pb.MxCommandReply
MxCommand = pb.MxCommand
MxEvent = pb.MxEvent
MxValue = pb.MxValue
Value = pb.MxValue
MxArray = pb.MxArray
MxStatusProxy = pb.MxStatusProxy
ProtocolStatus = pb.ProtocolStatus
RegisterCommand = pb.RegisterCommand
UnregisterCommand = pb.UnregisterCommand
AddItemCommand = pb.AddItemCommand
AddItem2Command = pb.AddItem2Command
RemoveItemCommand = pb.RemoveItemCommand
AdviseCommand = pb.AdviseCommand
UnAdviseCommand = pb.UnAdviseCommand
AddItemBulkCommand = pb.AddItemBulkCommand
AdviseItemBulkCommand = pb.AdviseItemBulkCommand
RemoveItemBulkCommand = pb.RemoveItemBulkCommand
// OpenSessionRequest is the gateway OpenSession request message.
OpenSessionRequest = pb.OpenSessionRequest
// OpenSessionReply is the gateway OpenSession reply message.
OpenSessionReply = pb.OpenSessionReply
// CloseSessionRequest is the gateway CloseSession request message.
CloseSessionRequest = pb.CloseSessionRequest
// CloseSessionReply is the gateway CloseSession reply message.
CloseSessionReply = pb.CloseSessionReply
// StreamEventsRequest is the gateway StreamEvents request message.
StreamEventsRequest = pb.StreamEventsRequest
// MxCommandRequest carries one MXAccess command for Invoke.
MxCommandRequest = pb.MxCommandRequest
// MxCommandReply is the reply to an MXAccess command Invoke.
MxCommandReply = pb.MxCommandReply
// MxCommand is the discriminated union of MXAccess command payloads.
MxCommand = pb.MxCommand
// MxEvent is one ordered event delivered on a session event stream.
MxEvent = pb.MxEvent
// MxValue is the protobuf representation of an MXAccess value.
MxValue = pb.MxValue
// Value is an alias for MxValue retained for symmetry with other clients.
Value = pb.MxValue
// MxArray is the protobuf representation of an MXAccess array value.
MxArray = pb.MxArray
// MxStatusProxy mirrors the MXAccess MXSTATUS_PROXY structure.
MxStatusProxy = pb.MxStatusProxy
// ProtocolStatus is the gateway-level status carried on every reply.
ProtocolStatus = pb.ProtocolStatus
// RegisterCommand is the payload of an MXAccess Register command.
RegisterCommand = pb.RegisterCommand
// UnregisterCommand is the payload of an MXAccess Unregister command.
UnregisterCommand = pb.UnregisterCommand
// AddItemCommand is the payload of an MXAccess AddItem command.
AddItemCommand = pb.AddItemCommand
// AddItem2Command is the payload of an MXAccess AddItem2 command.
AddItem2Command = pb.AddItem2Command
// RemoveItemCommand is the payload of an MXAccess RemoveItem command.
RemoveItemCommand = pb.RemoveItemCommand
// AdviseCommand is the payload of an MXAccess Advise command.
AdviseCommand = pb.AdviseCommand
// UnAdviseCommand is the payload of an MXAccess UnAdvise command.
UnAdviseCommand = pb.UnAdviseCommand
// AddItemBulkCommand is the payload of an AddItem bulk command.
AddItemBulkCommand = pb.AddItemBulkCommand
// AdviseItemBulkCommand is the payload of an Advise bulk command.
AdviseItemBulkCommand = pb.AdviseItemBulkCommand
// RemoveItemBulkCommand is the payload of a RemoveItem bulk command.
RemoveItemBulkCommand = pb.RemoveItemBulkCommand
// UnAdviseItemBulkCommand is the payload of an UnAdvise bulk command.
UnAdviseItemBulkCommand = pb.UnAdviseItemBulkCommand
SubscribeBulkCommand = pb.SubscribeBulkCommand
UnsubscribeBulkCommand = pb.UnsubscribeBulkCommand
WriteCommand = pb.WriteCommand
Write2Command = pb.Write2Command
RegisterReply = pb.RegisterReply
AddItemReply = pb.AddItemReply
AddItem2Reply = pb.AddItem2Reply
SubscribeResult = pb.SubscribeResult
BulkSubscribeReply = pb.BulkSubscribeReply
// SubscribeBulkCommand combines AddItem and Advise for a list of tags.
SubscribeBulkCommand = pb.SubscribeBulkCommand
// UnsubscribeBulkCommand combines UnAdvise and RemoveItem for a list of items.
UnsubscribeBulkCommand = pb.UnsubscribeBulkCommand
// WriteCommand is the payload of an MXAccess Write command.
WriteCommand = pb.WriteCommand
// Write2Command is the payload of an MXAccess Write2 command.
Write2Command = pb.Write2Command
// RegisterReply carries the ServerHandle returned by Register.
RegisterReply = pb.RegisterReply
// AddItemReply carries the ItemHandle returned by AddItem.
AddItemReply = pb.AddItemReply
// AddItem2Reply carries the ItemHandle returned by AddItem2.
AddItem2Reply = pb.AddItem2Reply
// SubscribeResult is one entry in a bulk command result list.
SubscribeResult = pb.SubscribeResult
// BulkSubscribeReply aggregates SubscribeResult entries for a bulk command.
BulkSubscribeReply = pb.BulkSubscribeReply
)
// Enumerations from the generated contract re-exported for client callers.
type (
MxCommandKind = pb.MxCommandKind
MxDataType = pb.MxDataType
MxEventFamily = pb.MxEventFamily
MxStatusCategory = pb.MxStatusCategory
MxStatusSource = pb.MxStatusSource
// MxCommandKind discriminates which MXAccess command an MxCommand carries.
MxCommandKind = pb.MxCommandKind
// MxDataType is the MXAccess data type tag on values and arrays.
MxDataType = pb.MxDataType
// MxEventFamily groups MXAccess events by source category.
MxEventFamily = pb.MxEventFamily
// MxStatusCategory classifies MXSTATUS_PROXY entries.
MxStatusCategory = pb.MxStatusCategory
// MxStatusSource identifies the originator of a status entry.
MxStatusSource = pb.MxStatusSource
// ProtocolStatusCode enumerates gateway-level status codes.
ProtocolStatusCode = pb.ProtocolStatusCode
SessionState = pb.SessionState
// SessionState enumerates gateway session lifecycle states.
SessionState = pb.SessionState
)
// MXAccess command kind, data type, and protocol status constants surfaced
// from the generated contract.
const (
CommandKindRegister = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
CommandKindUnregister = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
CommandKindAddItem = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
CommandKindAddItem2 = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
CommandKindRemoveItem = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM
CommandKindAdvise = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
CommandKindUnAdvise = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE
CommandKindAddItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK
CommandKindAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK
CommandKindRemoveItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK
// CommandKindRegister selects the MXAccess Register command.
CommandKindRegister = pb.MxCommandKind_MX_COMMAND_KIND_REGISTER
// CommandKindUnregister selects the MXAccess Unregister command.
CommandKindUnregister = pb.MxCommandKind_MX_COMMAND_KIND_UNREGISTER
// CommandKindAddItem selects the MXAccess AddItem command.
CommandKindAddItem = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM
// CommandKindAddItem2 selects the MXAccess AddItem2 command.
CommandKindAddItem2 = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM2
// CommandKindRemoveItem selects the MXAccess RemoveItem command.
CommandKindRemoveItem = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM
// CommandKindAdvise selects the MXAccess Advise command.
CommandKindAdvise = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE
// CommandKindUnAdvise selects the MXAccess UnAdvise command.
CommandKindUnAdvise = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE
// CommandKindAddItemBulk selects the AddItem bulk command.
CommandKindAddItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADD_ITEM_BULK
// CommandKindAdviseItemBulk selects the Advise bulk command.
CommandKindAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_ADVISE_ITEM_BULK
// CommandKindRemoveItemBulk selects the RemoveItem bulk command.
CommandKindRemoveItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_REMOVE_ITEM_BULK
// CommandKindUnAdviseItemBulk selects the UnAdvise bulk command.
CommandKindUnAdviseItemBulk = pb.MxCommandKind_MX_COMMAND_KIND_UN_ADVISE_ITEM_BULK
CommandKindSubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK
CommandKindUnsubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK
CommandKindWrite = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
CommandKindWrite2 = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
// CommandKindSubscribeBulk selects the AddItem+Advise combined bulk command.
CommandKindSubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_SUBSCRIBE_BULK
// CommandKindUnsubscribeBulk selects the UnAdvise+RemoveItem combined bulk command.
CommandKindUnsubscribeBulk = pb.MxCommandKind_MX_COMMAND_KIND_UNSUBSCRIBE_BULK
// CommandKindWrite selects the MXAccess Write command.
CommandKindWrite = pb.MxCommandKind_MX_COMMAND_KIND_WRITE
// CommandKindWrite2 selects the MXAccess Write2 command.
CommandKindWrite2 = pb.MxCommandKind_MX_COMMAND_KIND_WRITE2
// DataTypeUnknown denotes an unrecognized MXAccess data type.
DataTypeUnknown = pb.MxDataType_MX_DATA_TYPE_UNKNOWN
// DataTypeBoolean denotes an MXAccess Boolean value.
DataTypeBoolean = pb.MxDataType_MX_DATA_TYPE_BOOLEAN
// DataTypeInteger denotes an MXAccess Integer value.
DataTypeInteger = pb.MxDataType_MX_DATA_TYPE_INTEGER
DataTypeFloat = pb.MxDataType_MX_DATA_TYPE_FLOAT
DataTypeDouble = pb.MxDataType_MX_DATA_TYPE_DOUBLE
DataTypeString = pb.MxDataType_MX_DATA_TYPE_STRING
DataTypeTime = pb.MxDataType_MX_DATA_TYPE_TIME
// DataTypeFloat denotes an MXAccess Float (single precision) value.
DataTypeFloat = pb.MxDataType_MX_DATA_TYPE_FLOAT
// DataTypeDouble denotes an MXAccess Double (double precision) value.
DataTypeDouble = pb.MxDataType_MX_DATA_TYPE_DOUBLE
// DataTypeString denotes an MXAccess String value.
DataTypeString = pb.MxDataType_MX_DATA_TYPE_STRING
// DataTypeTime denotes an MXAccess timestamp value.
DataTypeTime = pb.MxDataType_MX_DATA_TYPE_TIME
ProtocolStatusOK = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK
// ProtocolStatusOK indicates the gateway processed the request successfully.
ProtocolStatusOK = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_OK
// ProtocolStatusMxAccessFailure indicates the worker reported an MXAccess failure.
ProtocolStatusMxAccessFailure = pb.ProtocolStatusCode_PROTOCOL_STATUS_CODE_MXACCESS_FAILURE
)