kmsvc-sdk/README.md

# 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.