Align docs with StyleGuide and add CLAUDE.md

- Rename 16 kebab-case docs to PascalCase per StyleGuide - Move per-language client design docs from docs/ to clients/<lang>/ alongside their READMEs - Add ## Related Documentation sections to 15 docs that lacked one - Fix sentence-case violations in H3 headings (StyleGuide rule) - Update cross-references in gateway.md, client READMEs, scripts, and generate-proto.ps1 helpers to follow the new paths - Add CLAUDE.md with build/test commands, the source-update verification matrix, the parity-first contract, and pointers to MXAccess and Galaxy Repository analysis sources Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-30 10:19:22 -04:00
parent 133c83029b
commit 51a9dadf62
45 changed files with 522 additions and 134 deletions
@@ -0,0 +1,185 @@
+# Go Client Detailed Design
+
+## Purpose
+
+Provide an idiomatic Go client module for MXAccess Gateway, plus a test CLI and
+unit tests. The Go client should be suitable for services and command-line
+automation.
+
+Follow the [Go Style Guide](../../docs/style-guides/GoStyleGuide.md) for handwritten
+code and the [Protobuf Style Guide](../../docs/style-guides/ProtobufStyleGuide.md) for
+generated contract inputs.
+
+## Module Layout
+
+Recommended layout:
+
+```text
+clients/go/
+  go.mod
+  mxgateway/
+    client.go
+    session.go
+    options.go
+    auth.go
+    values.go
+    errors.go
+  internal/generated/
+    mxaccess_gateway.pb.go
+    mxaccess_gateway_grpc.pb.go
+  cmd/mxgw-go/
+    main.go
+  tests/
+```
+
+Generated code should come from `protoc` plus:
+
+- `protoc-gen-go`
+- `protoc-gen-go-grpc`
+
+## Library API
+
+Suggested API:
+
+```go
+type Client struct {
+    // owns grpc.ClientConn
+}
+
+type Options struct {
+    Endpoint           string
+    APIKey             string
+    Plaintext          bool
+    CACertFile         string
+    ServerNameOverride string
+    DialTimeout        time.Duration
+    CallTimeout        time.Duration
+}
+
+func Dial(ctx context.Context, opts Options) (*Client, error)
+func (c *Client) OpenSession(ctx context.Context, opts OpenSessionOptions) (*Session, error)
+func (c *Client) Invoke(ctx context.Context, req *pb.MxCommandRequest) (*pb.MxCommandReply, error)
+func (c *Client) Close() error
+```
+
+Session:
+
+```go
+type Session struct {
+    ID string
+}
+
+func (s *Session) Register(ctx context.Context, clientName string) (int32, error)
+func (s *Session) Unregister(ctx context.Context, serverHandle int32) error
+func (s *Session) AddItem(ctx context.Context, serverHandle int32, item string) (int32, error)
+func (s *Session) AddItem2(ctx context.Context, serverHandle int32, item, context string) (int32, error)
+func (s *Session) Advise(ctx context.Context, serverHandle, itemHandle int32) error
+func (s *Session) AddItemBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*pb.SubscribeResult, error)
+func (s *Session) AdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) RemoveItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) UnAdviseItemBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) SubscribeBulk(ctx context.Context, serverHandle int32, tagAddresses []string) ([]*pb.SubscribeResult, error)
+func (s *Session) UnsubscribeBulk(ctx context.Context, serverHandle int32, itemHandles []int32) ([]*pb.SubscribeResult, error)
+func (s *Session) Write(ctx context.Context, serverHandle, itemHandle int32, value Value, userID int32) error
+func (s *Session) Events(ctx context.Context) (<-chan EventResult, error)
+func (s *Session) Close(ctx context.Context) error
+```
+
+## Authentication
+
+Use a unary and stream interceptor to attach:
+
+```text
+authorization: Bearer <api key>
+```
+
+The interceptor should use `metadata.AppendToOutgoingContext` or call options.
+Do not print API keys in errors.
+
+## TLS
+
+Support:
+
+- `credentials/insecure` for local plaintext,
+- `credentials.NewClientTLSFromFile`,
+- custom `tls.Config` for advanced callers.
+
+## Streaming
+
+`Events(ctx)` should return a receive channel of:
+
+```go
+type EventResult struct {
+    Event *pb.MxEvent
+    Err   error
+}
+```
+
+The receive goroutine exits on stream end, context cancellation, or error. The
+channel should be closed exactly once. Do not reorder events.
+
+## Error Handling
+
+Expose typed errors:
+
+```go
+type GatewayError struct { ... }
+type CommandError struct { ... }
+type MxAccessError struct { ... }
+```
+
+Use `errors.Is` / `errors.As` support. Preserve raw protobuf replies on command
+errors.
+
+## Test CLI
+
+Binary: `mxgw-go`.
+
+Recommended commands:
+
+```text
+mxgw-go version
+mxgw-go smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestChildObject.TestInt
+mxgw-go write --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123
+mxgw-go stream-events --session-id <id> --json
+```
+
+Recommended CLI library:
+
+- standard `flag` for minimalism, or
+- Cobra if subcommand ergonomics matter.
+
+## Unit Tests
+
+Use `bufconn` for in-memory gRPC tests.
+
+Required tests:
+
+- auth interceptor on unary calls,
+- auth interceptor on streaming calls,
+- plaintext and TLS dial options,
+- command helper request construction,
+- value conversion,
+- status conversion,
+- typed error wrapping,
+- stream channel closes on cancellation,
+- late stream error propagation,
+- CLI JSON redaction.
+
+## Integration Tests
+
+Use Go build tags or environment skip:
+
+```text
+MXGATEWAY_INTEGRATION=1
+```
+
+Integration test should run `OpenSession`, `Register`, `AddItem`, `Advise`,
+bounded `StreamEvents`, and `CloseSession`.
+
+## Related Documentation
+
+- [Client Libraries Detailed Design](../../docs/ClientLibrariesDesign.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Client Packaging](../../docs/ClientPackaging.md)
+- [Go Style Guide](../../docs/style-guides/GoStyleGuide.md)
@@ -3,7 +3,7 @@
 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
+`../../docs/ClientProtoGeneration.md` so gateway and client contracts stay in
 sync.

 ## Layout
@@ -28,7 +28,7 @@ Run generation after the shared `.proto` files or the Go output path changes:
 ./generate-proto.ps1
 ```

-The script uses the tool paths recorded in `../../docs/toolchain-links.md`.
+The script uses the tool paths recorded in `../../docs/ToolchainLinks.md`.

 ## Build And Test

@@ -209,5 +209,5 @@ go run ./cmd/mxgw-go smoke -endpoint $env:MXGATEWAY_ENDPOINT -plaintext -api-key
 ## Related Documentation

 - [Client Packaging](../../docs/ClientPackaging.md)
- [Client Proto Generation](../../docs/client-proto-generation.md)
- [Go Client Detailed Design](../../docs/clients-golang-design.md)
+- [Client Proto Generation](../../docs/ClientProtoGeneration.md)
+- [Go Client Detailed Design](./GoClientDesign.md)
@@ -9,13 +9,13 @@ $protoc = 'C:\Users\dohertj2\AppData\Local\Microsoft\WinGet\Packages\Google.Prot
 $goPluginPath = 'C:\Users\dohertj2\go\bin'

 if (-not (Test-Path $protoc)) {
-    throw "protoc was not found at $protoc. See docs/toolchain-links.md."
+    throw "protoc was not found at $protoc. See docs/ToolchainLinks.md."
 }

 foreach ($pluginName in @('protoc-gen-go.exe', 'protoc-gen-go-grpc.exe')) {
    $pluginPath = Join-Path $goPluginPath $pluginName
    if (-not (Test-Path $pluginPath)) {
-        throw "$pluginName was not found at $pluginPath. See docs/toolchain-links.md."
+        throw "$pluginName was not found at $pluginPath. See docs/ToolchainLinks.md."
    }
 }