kmsvc-sdk

Go client SDK for the Kafka Management Service message-plane API (kafkamgmt.v1). Wraps the generated gRPC client from 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

export GOPRIVATE=forgejo.riotpiao.homelab.com   # self-hosted Forgejo, skip public proxy/sumdb
go get forgejo.riotpiao.homelab.com/homelab/kmsvc-sdk@latest

Usage

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:

if errors.Is(err, kmsvc.ErrQueueNotFound) { ... }

See errors.go for the full list.

Development

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.

Final test - clean cache removal

Final CI validation - Forgejo ready

1.7 KiB Raw Blame History