# apigenie-generator client go (AsyncAPI)

Source: https://apigenie.pl/docs/reference/generator/client-go-asyncapi
Part of the reference of [apigenie-generator](https://apigenie.pl/docs/reference/generator.md).
Its other pages: [Conformance results](https://apigenie.pl/docs/reference/generator/conformance.md), [docs](https://apigenie.pl/docs/reference/generator/docs.md), [data](https://apigenie.pl/docs/reference/generator/data.md), [schema zod](https://apigenie.pl/docs/reference/generator/schema-zod.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir.md), [client fetch](https://apigenie.pl/docs/reference/generator/client-fetch.md), [client go](https://apigenie.pl/docs/reference/generator/client-go.md), [client java](https://apigenie.pl/docs/reference/generator/client-java.md), [client python](https://apigenie.pl/docs/reference/generator/client-python.md), [client rust](https://apigenie.pl/docs/reference/generator/client-rust.md), [client swift](https://apigenie.pl/docs/reference/generator/client-swift.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet.md), [server axum](https://apigenie.pl/docs/reference/generator/server-axum.md), [server express](https://apigenie.pl/docs/reference/generator/server-express.md), [server fastapi](https://apigenie.pl/docs/reference/generator/server-fastapi.md), [server go](https://apigenie.pl/docs/reference/generator/server-go.md), [server hummingbird](https://apigenie.pl/docs/reference/generator/server-hummingbird.md), [server mcp](https://apigenie.pl/docs/reference/generator/server-mcp.md), [server orpc](https://apigenie.pl/docs/reference/generator/server-orpc.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring.md), [server vapor](https://apigenie.pl/docs/reference/generator/server-vapor.md), [client csharp](https://apigenie.pl/docs/reference/generator/client-csharp-asyncapi.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-asyncapi.md), [client java](https://apigenie.pl/docs/reference/generator/client-java-asyncapi.md), [client kafkajs](https://apigenie.pl/docs/reference/generator/client-kafkajs.md), [client python](https://apigenie.pl/docs/reference/generator/client-python-asyncapi.md), [client ws](https://apigenie.pl/docs/reference/generator/client-ws.md), [server aspnet](https://apigenie.pl/docs/reference/generator/server-aspnet-asyncapi.md), [server faststream](https://apigenie.pl/docs/reference/generator/server-faststream.md), [server go](https://apigenie.pl/docs/reference/generator/server-go-asyncapi.md), [server kafkajs](https://apigenie.pl/docs/reference/generator/server-kafkajs.md), [server phoenix](https://apigenie.pl/docs/reference/generator/server-phoenix-asyncapi.md), [server spring](https://apigenie.pl/docs/reference/generator/server-spring-asyncapi.md), [server ws](https://apigenie.pl/docs/reference/generator/server-ws.md), [client elixir](https://apigenie.pl/docs/reference/generator/client-elixir-protobuf.md), [server elixir-grpc](https://apigenie.pl/docs/reference/generator/server-elixir-grpc.md), [server absinthe](https://apigenie.pl/docs/reference/generator/server-absinthe.md).

[Tier 2](/docs/reference/generator/conformance#tiers) · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · [Verification](#verification)

Generate a Go Kafka client package for the Kafka channels of an AsyncAPI document.

## Usage

```sh
apigenie-generator client go [...OPTIONS] INPUT_FILE
```

## Description

`apigenie-generator client go` generates from OpenAPI documents (see
[`apigenie-generator client go`](/docs/reference/generator/client-go)) and from AsyncAPI 3.x documents,
telling them apart by their `openapi` or `asyncapi` field. Documents referencing other files are
bundled first.

From an AsyncAPI document it generates a Go module (Go 1.22) with one package, using the Kafka
client [franz-go](https://github.com/twmb/franz-go) (`github.com/twmb/franz-go/pkg/kgo`, pinned
at v1.18.1 in `go.mod`, with a complete `go.sum`). By default the client is the counterpart of
the application the document describes: it sends the messages of the application's `receive`
operations and receives those of its `send` operations. Set the `perspective` option to
`application` to generate the described application's side instead.
[`apigenie-generator server go`](/docs/reference/generator/server-go-asyncapi) generates the other
side as an application with its own `main.go`.

The generator writes the Kafka channels: the channels of servers with the `kafka` or
`kafka-secure` protocol, and channels with a Kafka binding in documents without servers. Channels
of other protocols are skipped and reported as info.

With `perspective: application`, the client of the Carpet Express Event Platform sends the
shipment events and requests labels:

```go
client, err := events.NewClient(events.Options{
	Brokers:  []string{"localhost:9092"},
	ClientID: "label-printer",
})
if err != nil {
	log.Fatal(err)
}
defer client.Close()

// a sent operation with several messages takes any of them
err = client.SendPublishShipmentEvents(ctx, delivered)

// request/reply: waits for the reply with the request's correlation id
reply, err := client.RequestLabelRender(ctx, request)
switch reply := reply.(type) {
case events.LabelRendered:
	fmt.Println(reply.Payload.URL)
case events.LabelRenderFailed:
	fmt.Println(reply.Payload.Title)
}
```

In the default perspective, it receives them and renders the labels:

```go
type labelFarm struct{}

func (labelFarm) OnRenderLabel(ctx context.Context, message events.RenderLabel) (events.RequestLabelRenderReply, error) {
	var reply events.LabelRendered
	reply.Key = message.Key
	reply.Payload = render(message.Payload)
	return reply, nil // sent to TopicLabelRenderResults with the request's correlation id
}

func (labelFarm) OnUnknown(ctx context.Context, record *kgo.Record) error { return nil }

// received operations are consumed in the background until Close
err = client.ListenRequestLabelRender(labelFarm{})
err = client.ListenPublishShipmentEvents(shipmentTracker{})
```

The package is named by `package_name`, `--package-name` or the document's title (letters and
digits, lower case):

| File | Contents |
| ---- | -------- |
| `types.gen.go` | the types of the schemas the payloads use: structs with `json` tags, enums, and unions as a struct whose `Value` holds one variant of a sealed interface; each with a `Validate` method |
| `messages.gen.go` | a struct per message (`Key`, `Headers`, `Payload`), its headers struct and header constants, and the code writing, reading and validating records |
| `kafka.gen.go` | the server hosts, topics, group and client ids, the handler and message interfaces, and `Client` |
| `avro.gen.go` | the structs of the Avro records of the payloads, with their schemas and codecs |
| `security.gen.go` | the security schemes of the servers and the franz-go options of each |
| `runtime_*.gen.go` | the Kafka runtime (consumers, requesters, headers), validation, `Nullable[T]`, `Date` |
| `go.mod`, `go.sum` | the module, requiring franz-go |

- **The client.** `NewClient(options)` creates the producer and, for every operation with a
  reply, one consumer of its reply topic that all of that operation's requests share. `Close`
  stops the listeners, commits the offsets of the records they handled, leaves their consumer
  groups and closes the clients. `Options` takes the brokers, `ClientID` (replacing the
  generated `ProducerClientID`), `ClientOptions` (franz-go options added to every client, e.g.
  `kgo.AllowAutoTopicCreation` or those of [a security scheme](#security)), `GroupIDs`
  (consumer groups by operation id), `OnError`, `ReplyTimeout` and `SchemaRegistry` (the ids of
  [Avro schemas](#avro-payloads)).
- **Sent operations.** `Send<Operation>(ctx, message)` validates the message, writes its key,
  its headers (constant headers such as the `ce_specversion` and `ce_type` of CloudEvents
  included) and its JSON payload to the operation's topic, and returns once the brokers have it.
  With several messages, it takes an interface (`PublishShipmentEventsMessage`) that each of them
  implements.
- **Request/reply** with a reply channel: `Request<Operation>(ctx, message)` sets a new
  correlation id unless the message has one, sends the request and waits for the reply with that
  id until the context is done (`Options.ReplyTimeout`, 30 seconds by default, when the context
  has no deadline). It returns the reply message, or an interface of the reply messages
  (`RequestLabelRenderReply`) when there are several. An operation named after the verb isn't
  repeated: `requestLabelRender` gives `RequestLabelRender`.
- **Received operations.** `Listen<Operation>(handler)` consumes the operation's topic in the
  background, in its consumer group, until `Close`. The handler interface
  (`PublishShipmentEventsHandler`) has an `On<Message>` method per message and `OnUnknown`.
  Several messages are told apart by a payload property or a header with a distinct constant
  value (e.g. `type` or `ce_type`); otherwise the first message whose payload decodes strictly
  and is valid is chosen. Records that aren't valid messages, and handler errors, go to
  `Options.OnError` (logged by default). An operation with a reply gets `On<Message>(ctx,
  message) (Reply, error)`: the reply is sent to the reply topic with the request's correlation
  id copied.

Group and client ids come from the Kafka operation bindings as for
[`apigenie-generator server go`](/docs/reference/generator/server-go-asyncapi#description).

### Security

Each SASL or client certificate scheme of the Kafka servers is a constant of `security.gen.go`
(`SecurityKafkaScram`), with its key as value, and a function returning the franz-go options of
the scheme: `KafkaScramSecurity(username, password)` for SASL, `KafkaMtlsSecurity(certFile,
keyFile, caFile)` for a client certificate. `SecurityFromEnvironment(scheme)` takes the credentials
from environment variables named after the scheme key, e.g. `KAFKA_SCRAM_USERNAME` and
`KAFKA_SCRAM_PASSWORD`; add what it returns to `Options.ClientOptions`:

```go
security, err := events.SecurityFromEnvironment(events.SecurityKafkaScram)
if err != nil {
	log.Fatal(err)
}
client, err := events.NewClient(events.Options{Brokers: brokers, ClientOptions: security})
```

| Scheme | Options of franz-go |
| ------ | ------------------- |
| `scramSha256`, `scramSha512` | `kgo.SASL` with the SCRAM mechanism of `<KEY>_USERNAME` and `<KEY>_PASSWORD`, and `kgo.DialTLSConfig` on `kafka-secure` servers |
| `plain`, `userPassword` | the same with SASL PLAIN |
| `X509` | `kgo.DialTLSConfig` with the PEM files named by `<KEY>_CERT` (the client certificate), `<KEY>_KEY` (its private key) and `<KEY>_CA` (the CA certificates) |

Other schemes (`gssapi`, `oauth2`, ...) are left out with a warning.

### Avro payloads

A message whose `schemaFormat` is an Avro one (`application/vnd.apache.avro;version=1.9.0`, with
or without `+json` or `+yaml`) carries a struct of its record schema as its payload, in
`avro.gen.go`, with `json` tags of the field names. Enums are string types with a constant per
symbol (`CarrierScanStatusAtHub`), fixed types byte arrays. The logical types `timestamp-millis`,
`timestamp-micros` and `date` are `time.Time`, `time-millis` and `time-micros` `time.Duration`; a
union with `null` is a pointer. A root schema that isn't a record, records with `decimal` fields
and unions of other types are skipped with a warning. The message struct is
`<Message>Message` when the record's name is the message's (`CarrierScanMessage`).

The generated codec writes and reads the payloads in Avro's binary encoding, with the id of the
writer's schema where the Kafka binding of the message says: before the payload (`schemaIdLocation:
payload`, Confluent's wire format) or in the `apicurio.value.globalId` header (`schemaIdLocation:
header`, `SchemaIDHeader`). `Send` methods get the id from `Options.SchemaRegistry`, by the subject
of `schemaLookupStrategy` (`TopicIdStrategy`, `{topic}-value`, by default), once per schema; without
one, from the Confluent-compatible registry at the `schemaRegistryUrl` of the Kafka binding of the
first Kafka server that has one, which registers the schema with `POST
/subjects/{subject}/versions`. `ConfluentSchemaRegistry` takes a URL and basic authentication:

```go
registry := events.ConfluentSchemaRegistry{URL: "https://schemas.events.carpetexpress.example", Username: "ingest", Password: os.Getenv("REGISTRY_PASSWORD")}
client, err := events.NewClient(events.Options{Brokers: brokers, SchemaRegistry: registry})
```

Listeners decode records with the schema of the generated struct, so the writer's schema must be
the same; a record that isn't a payload of it is rejected. Request/reply operations with Avro
messages are skipped with a warning.

Not supported, and reported as warnings: payloads of other non-JSON schema formats (the messages
are skipped, and operations left without a message too), reply addresses given by runtime
expressions, and Kafka topics with parameters.

Since 0.12.0, `Validate` checks `not`, the schemas of draft-07
`dependencies` and `if`/`then`/`else` when their
schemas use only `required` and the `const` and `enum` of properties. `contentEncoding: base64`
strings are `[]byte`. `prefixItems` tuples whose positions are references or scalars of one type
are slices of that type, checked position by position, as in [`server go`](/docs/reference/generator/server-go#types).


## Extensions

| Extension | Effect |
| --------- | ------ |
| `x-go-name` | name of the type of a schema, or of the field of a property |
| `x-go-type` | Go type of a schema, e.g. `decimal.Decimal`; with `x-go-type-import: {path: ...}` for its package |
| `x-go-type-skip-optional-pointer` | the optional property isn't a pointer |
| `x-go-json-ignore` | the field gets the tag `json:"-"` |
| `x-omitempty` | `true` or `false` overrides the `omitempty` of the field |
| `x-enum-varnames`, `x-enumNames` | names of the enum constants |
| `x-enum-descriptions` | comments of the enum constants |
| `x-apigenie.codegen.name` | name of the type of a component schema, when it has no `x-go-name` |
| `x-apigenie.codegen.disabled` | `true` on a channel or an operation leaves it out (with the operations of a channel left out) |

The extensions can live in an overlay for this target instead of in the document, e.g.
`go.overlay.yaml`:

```yaml
overlay: 1.0.0
info:
  title: Go types
  version: 1.0.0
actions:
  - target: $.components.schemas.Order
    update:
      x-go-name: PurchaseOrder
  - target: $.components.schemas.Order.properties.total
    update:
      x-go-type: decimal.Decimal
      x-go-type-import:
        path: github.com/shopspring/decimal
```

```sh
apigenie-generator client go asyncapi.yaml --overlay go.overlay.yaml -o out
```

## Options

### -c, --config

Path to the configuration file to use. See the "Configuration" section for more information.

### --overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the
extensions of the "Extensions" section. Can be repeated: the overlays apply in order, after those
listed under `commands.generate.client_go.overlay` in the configuration file (with paths relative to
it). Warnings and errors about a value an overlay set point to the overlay. The overlays apply to
the AsyncAPI document bundled with the files it references.

### --strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated)
instead of a warning (`OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.`).

### --check

Writes nothing: compares what the generator would write with the output directory, prints the
files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See
[Check that generated code is up to date](/docs/reference/generator#check-that-generated-code-is-up-to-date).

### -o, --output

Directory where the module is generated.

### --package-name

Name of the Go package, as letters and digits in lower case (`carpet-express-events` gives
`carpetexpressevents`); defaults to the title of the API (`events` when it gives no valid
name). Its kebab case is the base of default group and client ids.

### --package-version

Ignored: Go modules have no version in `go.mod`.

### -p, --property

Applies to OpenAPI documents only; using it with an AsyncAPI document is an error.

## Configuration

The options are read from the `asyncapi` section of the configuration of `apigenie-generator client go`;
its other keys configure the generation from OpenAPI documents.

```yaml
version: '1.0'
commands:
  generate:
    client_go:
      asyncapi:
        module_path: github.com/acme/events
        package_name: events
        initialisms: [SKU]
        perspective: counterpart
```

| Option | Description |
| ------ | ----------- |
| `module_path` | Module path of `go.mod` (default: `example.com/<package>`) |
| `package_name` | Name of the package, a lower-case Go identifier (default: from `--package-name` or the title) |
| `initialisms` | Words written in capitals in identifiers, besides the common ones (`ID`, `URL`, ...) |
| `perspective` | `counterpart` (default): the counterpart of the described application; `application`: the described application, sending what it sends |

## Verification

The [codegen conformance suite](/docs/reference/generator#conformance-checks) runs this target on the Carpet Express AsyncAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. [All targets](/docs/reference/generator/conformance#asyncapi).

This target's support tier is [Tier 2](/docs/reference/generator/conformance#tiers). It goes through all three levels before every release, like Tier 1. It doesn't aim to support every feature: a feature of the fixture can stay unsupported, with the reason its manifest gives.

| Results | Level 1 | Level 2 | Level 3 |
| --- | --- | --- | --- |
| Release 0.12.0, `client go` | ✓ snapshots of 3.0; 31 supported, 0 not yet | ✓ pass (go version go1.22.5 linux/amd64) | ✓ 14 of 14 operations pass (go version go1.22.5 linux/amd64) |
| Release 0.12.0, `client go (application)` | ✓ snapshots of 3.0; 31 supported, 0 not yet | ✓ pass (go version go1.22.5 linux/amd64) | ✓ 14 of 14 operations pass (go version go1.22.5 linux/amd64) |
| Development version, `client go` | ✓ snapshots of 3.0; 31 supported, 0 not yet | runs before a release | runs before a release |
| Development version, `client go (application)` | ✓ snapshots of 3.0; 31 supported, 0 not yet | runs before a release | runs before a release |
