# Package layout

This document describes the package layout within franz-go. Reading this
document should help you to understand how this library is supposed to be used.

franz-go consists of multiple Go packages, where each serves its own purpose.
The primary package is `kgo`, but supplementary packages are to be used as
necessary (for example, for sasl authentication).

## Package [kgo](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo)

The package `kgo` is the main package as it provides all the core functionality
to interact with Kafka.  It has support for transactions, regex topic
consuming, the latest partitioning strategies, data loss detection, closest
replica fetching, and more. If a client [KIP][1] exists, this library aims to
support it.

[1]: https://cwiki.apache.org/confluence/display/KAFKA/Kafka+Improvement+Proposals

This library attempts to provide an intuitive API _while_ interacting with
Kafka the way Kafka expects (timeouts, etc.). In some cases, this makes the
tricky corners of Kafka more explicit and manual to deal with correctly. In the
general case, though, I hope this library is satisfactory.

## Package [kmsg](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kmsg)

The main package is `kgo`, but `kmsg` also exists, containing autogenerated code
for every request and response type. `kmsg` implements the messages as defined
in the Kafka protocol. You will want to use this package if you need more
control how to access Kafka, or you are using an API within the kgo package
that requires you to process a pure Kafka struct definition. A common use case
is constructing and sending admin api requests.

Usage:

```go
req := kmsg.NewMetadataRequest()
res, err := req.RequestWith(ctx, client)
if err != nil {
    panic(err) // error during request has happened (e. g. context cancelled)
}
```

## Package [sasl](https://pkg.go.dev/github.com/twmb/franz-go/pkg/sasl)

Package `sasl` specifies interfaces that any sasl authentication (PLAIN,
GSSAPI, SCRAM, ...) must provide to interop with Kafka SASL. This package is
more specific to SASL and not to Kafka - hence it has its own package, and
hence the lack of a `k` prefix in the package name.

Usage:

```go
seeds := []string{"localhost:9092"}

// SASL Plain credentials
user := ""
password := ""

opts := []kgo.Opt{
    kgo.SeedBrokers(seeds...),
    // SASL Options
    kgo.SASL(plain.Auth{
        User: user,
        Pass: password,
    }.AsMechanism()),
}
client, err := kgo.NewClient(opts...)
```

## Package [kversion](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kversion)

Package `kversion` specifies api key versions corresponding to Kafka versions.
Kafka technically has internal broker versions that bump multiple times per
release. The kversion package defines only releases and tip (and stable, which
matches the most recent release).

You usually use this package to set the max or min versions that are acceptable
for requests issued with the kgo package, however, there are additional
miscellaneous useful functions related to Kafka api key versioning.

Setting a max version may be important to you if you use any `kmsg` type
directly and do not call the type's `Default` function. If you do this, then
you may accidentally opt in to a new field's default 0 value being important
and triggering unforeseen behavior. If you pin the client with a
[`MaxVersions`](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kgo#MaxVersions)
option, you can prevent this.

Additionally, if you are a client talking to brokers of unknown version, you
may want to avoid downgrading a request too much to avoid a field in the
request being silently elided.

Usage:

```go
client, err := kgo.NewClient(
    kgo.SeedBrokers(seeds...),
    kgo.MaxVersions(kversion.V2_4_0()),
    kgo.MinVersions(kversion.V1_0_0()),
)
```

## Package [kerr](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kerr)

Package `kerr` is dedicated to all Kafka errors. Most responses from Kafka
contain an `ErrorCode` field somewhere within it. The `kerr` package can be
used to translate that int16 error code into meaningful text.

Usage:

```go
err := kerr.ErrorForCode(response.ErrorCode)
if err != nil {
    // Handle error
}
```

## Package [kbin](https://pkg.go.dev/github.com/twmb/franz-go/pkg/kbin)

Package `kbin` is a small utility package that is for speaking the binary
protocol that Kafka speaks. This is useful for reading from and writing
to Kafka.