1# Package layout
2
3This document describes the package layout within franz-go. Reading this
4document should help you to understand how this library is supposed to be used.
5
6franz-go consists of multiple Go packages, where each serves its own purpose.
7The primary package is `kgo`, but supplementary packages are to be used as
8necessary (for example, for sasl authentication).
9
10## Package [kgo](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo)
11
12The package `kgo` is the main package as it provides all the core functionality
13to interact with Kafka. It has support for transactions, regex topic
14consuming, the latest partitioning strategies, data loss detection, closest
15replica fetching, and more. If a client [KIP][1] exists, this library aims to
16support it.
17
18[1]: https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals
19
20This library attempts to provide an intuitive API _while_ interacting with
21Kafka the way Kafka expects (timeouts, etc.). In some cases, this makes the
22tricky corners of Kafka more explicit and manual to deal with correctly. In the
23general case, though, I hope this library is satisfactory.
24
25## Package [kmsg](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kmsg)
26
27The main package is `kgo`, but `kmsg` also exists, containing autogenerated code
28for every request and response type. `kmsg` implements the messages as defined
29in the Kafka protocol. You will want to use this package if you need more
30control how to access Kafka, or you are using an API within the kgo package
31that requires you to process a pure Kafka struct definition. A common use case
32is constructing and sending admin api requests.
33
34Usage:
35
36```go
37req := kmsg.NewMetadataRequest()
38res, err := req.RequestWith(ctx, client)
39if err != nil {
40 panic(err) // error during request has happened (e. g. context cancelled)
41}
42```
43
44## Package [sasl](https://pkg.go.dev/github.com/twmb/franz-go/pkg/sasl)
45
46Package `sasl` specifies interfaces that any sasl authentication (PLAIN,
47GSSAPI, SCRAM, ...) must provide to interop with Kafka SASL. This package is
48more specific to SASL and not to Kafka - hence it has its own package, and
49hence the lack of a `k` prefix in the package name.
50
51Usage:
52
53```go
54seeds := []string{"localhost:9092"}
55
56// SASL Plain credentials
57user := ""
58password := ""
59
60opts := []kgo.Opt{
61 kgo.SeedBrokers(seeds...),
62 // SASL Options
63 kgo.SASL(plain.Auth{
64 User: user,
65 Pass: password,
66 }.AsMechanism()),
67}
68client, err := kgo.NewClient(opts...)
69```
70
71## Package [kversion](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kversion)
72
73Package `kversion` specifies api key versions corresponding to Kafka versions.
74Kafka technically has internal broker versions that bump multiple times per
75release. The kversion package defines only releases and tip (and stable, which
76matches the most recent release).
77
78You usually use this package to set the max or min versions that are acceptable
79for requests issued with the kgo package, however, there are additional
80miscellaneous useful functions related to Kafka api key versioning.
81
82Setting a max version may be important to you if you use any `kmsg` type
83directly and do not call the type's `Default` function. If you do this, then
84you may accidentally opt in to a new field's default 0 value being important
85and triggering unforeseen behavior. If you pin the client with a
86[`MaxVersions`](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#MaxVersions)
87option, you can prevent this.
88
89Additionally, if you are a client talking to brokers of unknown version, you
90may want to avoid downgrading a request too much to avoid a field in the
91request being silently elided.
92
93Usage:
94
95```go
96client, err := kgo.NewClient(
97 kgo.SeedBrokers(seeds...),
98 kgo.MaxVersions(kversion.V2_4_0()),
99 kgo.MinVersions(kversion.V1_0_0()),
100)
101```
102
103## Package [kerr](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kerr)
104
105Package `kerr` is dedicated to all Kafka errors. Most responses from Kafka
106contain an `ErrorCode` field somewhere within it. The `kerr` package can be
107used to translate that int16 error code into meaningful text.
108
109Usage:
110
111```go
112err := kerr.ErrorForCode(response.ErrorCode)
113if err != nil {
114 // Handle error
115}
116```
117
118## Package [kbin](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kbin)
119
120Package `kbin` is a small utility package that is for speaking the binary
121protocol that Kafka speaks. This is useful for reading from and writing
122to Kafka.
View as plain text