apigenie-generator client go (AsyncAPI)
Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate a Go Kafka client package for the Kafka channels of an AsyncAPI document.
Usage
apigenie-generator client go [...OPTIONS] INPUT_FILE
Description
apigenie-generator client go generates from OpenAPI documents (see
apigenie-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 (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 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:
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:
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.Closestops the listeners, commits the offsets of the records they handled, leaves their consumer groups and closes the clients.Optionstakes the brokers,ClientID(replacing the generatedProducerClientID),ClientOptions(franz-go options added to every client, e.g.kgo.AllowAutoTopicCreationor those of a security scheme),GroupIDs(consumer groups by operation id),OnError,ReplyTimeoutandSchemaRegistry(the ids of Avro schemas). - Sent operations.
Send<Operation>(ctx, message)validates the message, writes its key, its headers (constant headers such as thece_specversionandce_typeof 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:requestLabelRendergivesRequestLabelRender. - Received operations.
Listen<Operation>(handler)consumes the operation’s topic in the background, in its consumer group, untilClose. The handler interface (PublishShipmentEventsHandler) has anOn<Message>method per message andOnUnknown. Several messages are told apart by a payload property or a header with a distinct constant value (e.g.typeorce_type); otherwise the first message whose payload decodes strictly and is valid is chosen. Records that aren’t valid messages, and handler errors, go toOptions.OnError(logged by default). An operation with a reply getsOn<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.
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:
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:
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.
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:
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
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.
-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.
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 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.
This target's support tier is Tier 2. 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 |