riotpiaoleandClaude Haiku 4.5
e4017aea9e
- Add Forgejo CI workflow: gofmt checks, module caching, coverage reporting - Add release workflow: auto-tag-triggered release with changelog extraction - Update module paths from rock/ to homelab/ namespace - Enhance test coverage and documentation (PLAN.md, README.md) Co-Authored-By: Claude Haiku 4.5 <[email protected]>
59 lines
1.6 KiB
Markdown
59 lines
1.6 KiB
Markdown
# 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/homelab/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/homelab/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.
|