feat: initial kmsvc-sdk Go client for kafkamgmt.v1 message-plane API

Client/auth/message-plane methods/long-poll/typed errors, all tested against an in-process bufconn fake. Consumes [email protected] via go get (GOPRIVATE), no submodule or local codegen.
2026-06-21 19:57:41 -07:00
commit 6ef58c108f
17 changed files with 1125 additions and 0 deletions
@@ -0,0 +1,58 @@
+# kmsvc-sdk
+
+Go client SDK for the Kafka Management Service message-plane API (`kafkamgmt.v1`). Wraps the generated gRPC client from [kmsvc-proto](https://forgejo.riotpiao.homelab.com/rock/kmsvc-proto) with ergonomic Go methods, bearer-token attachment, and long-poll handling — callers never touch raw protobuf types or gRPC metadata.
+
+Queue lifecycle (create/delete/configure) is managed via the Queue CRD on the cluster, not this SDK — see `kafaka_management_service` design.md §2a/§2b.
+
+## Install
+
+```bash
+export GOPRIVATE=forgejo.riotpiao.homelab.com   # self-hosted Forgejo, skip public proxy/sumdb
+go get forgejo.riotpiao.homelab.com/rock/kmsvc-sdk@latest
+```
+
+## Usage
+
+```go
+client, err := kmsvc.New(ctx, "kmsvc.homelab.internal:443",
+    kmsvc.WithTokenSource(kmsvc.StaticToken(token)),
+)
+if err != nil {
+    log.Fatal(err)
+}
+defer client.Close()
+
+out, err := client.SendMessage(ctx, kmsvc.SendMessageInput{
+    QueueName: "orders",
+    Body:      []byte(`{"order_id": 123}`),
+})
+
+msgs, err := client.ReceiveMessage(ctx, "orders", kmsvc.ReceiveOptions{
+    MaxNumberOfMessages: 10,
+    WaitTimeSeconds:      20,
+})
+for _, m := range msgs {
+    // process m.Body
+    client.DeleteMessage(ctx, "orders", m.ReceiptHandle)
+}
+```
+
+## Error handling
+
+gRPC status codes are mapped to exported sentinel errors:
+
+```go
+if errors.Is(err, kmsvc.ErrQueueNotFound) { ... }
+```
+
+See `errors.go` for the full list.
+
+## Development
+
+```bash
+export GOPRIVATE=forgejo.riotpiao.homelab.com
+go build ./...
+go test ./... -race
+```
+
+No `buf`/`protoc` install needed — `kmsvc-proto`'s generated Go code is consumed as a plain module dependency.