1# Admin Requests
2
3This repo provides two ways to issue admin requests: a high level [kadm][a]
4package, and a low level [kmsg][b] package. The kadm package is an opinionated
5package that attempts to abstract the low level details of administrating into
6some intuitive methods and types that have many helper functions. If you see a
7type that could have more helper functions, please create a pull request.
8
9[a]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kadm
10[b]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kmsg
11
12Not all of the low level API can be encapsulated in a high level API, and the
13kadm package must sacrifice some details to make things easier to use. If the
14kadm package does not give you the control you need, the low level kmsg package
15allows you to construct requests to Kafka directly.
16
17All Kafka requests and responses are supported through generated code in the
18kmsg package. The package aims to provide some relatively comprehensive
19documentation (at least more than Kafka itself provides), but may be lacking
20in some areas.
21
22Whenever using a struct from kmsg, create it with a `New` function. This calls
23`Default` on fields that have defaults, allowing you to avoid specifying
24everything all of the time. This makes your usage of kmsg more future proof,
25because any struct within that package can have fields added to it as Kafka
26adds fields.
27
28It is also recommended to consider using the kgo package's [`MaxVersions`][1]
29option. This will pin requests to a maximum version that you know you are in
30control of, which will avoid any field-addition issues as the client version
31advances.
32
33[1]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#MaxVersions
34
35It is recommended to always set all fields of a request. If you are talking to
36a broker that does not support all fields you intend to use, those fields are
37silently not written to that broker. It is recommended to ensure your brokers
38support what you are expecting to send them. If you want to absolutely ensure
39that some fields will not be ignored, you can use the [`MinVersions`][2]
40option. With this, if you try to write to a broker that does not support the
41version of a request you are writing, the client will not issue the request and
42will return a relevant error.
43
44[2]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#MinVersions
45
46To issue a kmsg request, use the client's [`Request`][3] or
47[`RequestSharded`][4] functions. The sharded requests is useful for any request
48that internally can be split and issued to many brokers (`ListOffsets`,
49`ListGroups`, etc.). Both functions are pretty overpowered; see the
50documentation on both for details.
51
52[3]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#Client.Request
53[4]: https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#Client.RequestSharded
54
55As an example of issuing a `MetadataRequest`,
56
57```go
58topics := []string{"foo", "bar"}
59
60req := kmsg.NewMetadataRequest()
61for _, topic := range topics {
62 reqTopic := kmsg.NewMetadataRequestTopic()
63 reqTopic.Topic = kmsg.StringPtr(topic)
64 req.Topics = append(req.Topics, reqTopic)
65}
66
67resp, err := req.RequestWith(ctx, client)
68
69// handle response...
70```
View as plain text