# apigenie-generator client elixir (AsyncAPI)

Source: https://apigenie.pl/docs/reference/generator/client-elixir-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 go](https://apigenie.pl/docs/reference/generator/client-go-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 an Elixir client library of the WebSocket and Kafka channels of an AsyncAPI document.

## Usage

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

## Description

`apigenie-generator client elixir` generates from OpenAPI documents (see
[`apigenie-generator client elixir`](/docs/reference/generator/client-elixir)) 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 Mix library (Elixir 1.18 or later) for the counterpart of
the described application, by default: it sends what the application receives and receives what
it sends. The WebSocket channels connect on [Mint.WebSocket](https://hexdocs.pm/mint_web_socket),
the Kafka channels use [brod](https://github.com/kafka4beam/brod). Set the `perspective` option
to `application` for the application's Kafka library; WebSocket channels are connected to in the
counterpart perspective only. With Kafka channels the library depends on
[snappyer](https://hex.pm/packages/snappyer), a NIF that needs a C++ compiler, so that brod reads
Snappy-compressed records (the default of Go's franz-go producers); LZ4 and zstd records need
`lz4b` or `ezstd` added by hand.

The generator writes the channels of servers with the `ws`/`wss` and `kafka`/`kafka-secure`
protocols, and channels with a WebSocket or Kafka binding in documents without servers. Channels
of other protocols (MQTT, AMQP, HTTP) are skipped and reported as info.

```elixir
{:ok, socket} =
  CarpetExpressEvents.WebSocket.TrackingStream.connect("shp_8Yb2Kk1qP0wZcT3uXr5sN7aD",
    url: "ws://localhost:4000",
    query: [include: ["location"]],
    headers: [accept_language: "de-DE"],
    credentials: %{"streamToken" => token},
    handler: MyApp.Tracking
  )

{:ok, pickup} = CarpetExpressEvents.WebSocket.PickupDesk.connect(url: "ws://localhost:4000")
{:ok, %CarpetExpressEvents.Models.PickupConfirmed{}} =
  CarpetExpressEvents.WebSocket.PickupDesk.request_pickup(pickup, request)
```

The library, for the application `carpet_express_events` (named by `app`, `--package-name` or
the document's title):

| File | Contents |
| ---- | -------- |
| `lib/<app>/models/*.ex` | the structs of the schemas the payloads use, decoded and encoded by `decode.ex` and `encode.ex` |
| `lib/<app>/websocket/<channel>.ex` | per WebSocket channel, `connect`, and the functions sending its messages and requests |
| `lib/<app>/websocket/<channel>/handler.ex` | the behaviour of the callbacks receiving what the server sends on the channel |
| `lib/<app>/messages/*.ex` | per Kafka message, a struct (`payload`, `headers`, `key`) and the description of its record |
| `lib/<app>/avro/*.ex` | the structs of the Avro records and the enums of the payloads, with their schemas |
| `lib/<app>/kafka/security.ex` | the security schemes of the Kafka servers and brod's client configuration of each |
| `lib/<app>/kafka.ex` | the supervisor of the Kafka processes and a function per topic |
| `lib/<app>/kafka/<operation>.ex` | per sent operation, its send (and request) functions; per received operation, the behaviour of its callbacks |
| `lib/<app>/kafka/<operation>_consumer.ex` | per received operation, its group subscriber |
| `lib/<app>/runtime/` | the WebSocket connection (`ChannelSocket`) and the Kafka runtime |
| `mix.exs`, `.formatter.exs`, `.credo.exs` | the project, a library without application |

- **WebSocket channels, two framings.** `connect` (with the channel's address parameters first)
  opens a connection to the server of `:url` and joins the channel. With `framing: :phoenix`, the
  default, it speaks the Phoenix Channels protocol (version 2) of `apigenie-generator server
  phoenix`: the socket `/socket/websocket`, the channel's topic (the address segments joined by
  `:`), the ws binding's `:query` as the join payload, a heartbeat every 30 seconds. With
  `framing: :plain` it connects to the channel's address, the query in the URL, and the frames
  are the messages of the AsyncAPI document. `send_<message>` sends a message; for a request,
  the function named after it waits for the reply: the reply to its ref in the Phoenix framing,
  the next message with the request's correlation id in the plain one. What the server sends is
  decoded into its struct and given to the callbacks of the channel's `Handler` behaviour (the
  `:handler` option), or sent to the calling process. `:headers` are the headers of the channel's
  ws binding, sent with the handshake.
- **WebSocket security.** `:credentials` maps the keys of the channel's security schemes to
  credentials, and `connect` sends those of the schemes the handshake carries: an API key as its
  query parameter, header or cookie, `{user, password}` as basic credentials, a bearer token
  (`oauth2`, `openIdConnect`, `http` bearer) as the `access_token` query parameter in the Phoenix
  framing and as the `Authorization` header in the plain one. The server accepts the credential
  of any one of the schemes.
- **Kafka.** Add `{CarpetExpressEvents.Kafka, brokers: "localhost:9092"}` to your supervision
  tree. `send_<message>/1` checks a message's headers and returns once the brokers have the
  record; `request_<message>/2` waits for the reply on the reply topic, matched by the
  correlation id (generated when the request has none; `:timeout`, 30 seconds by default). Each
  received operation has a consumer group (`:brod_group_subscriber_v2`) handing its records to
  the behaviour's callbacks, as `server phoenix` does: told apart by a constant header
  (`ce_type`), payload property or decoding, with the optional `on_unknown/1` and `on_invalid/2`;
  a replier's callback returns its reply, sent with the request's correlation id.

Group ids come from the `groupId` schemas of the Kafka operation bindings, else `<app in kebab
case>-<operation>`, and the consumer modules' configuration overrides them (`config :app,
<Consumer>, group_id: ..., offset_reset_policy: :earliest`). Client ids come from the `clientId`
schemas the same way: the producers' brod client has the application's, `<app in kebab case>` by
default, and each consumer of replies and group subscriber has a brod client with the operation's.

The Kafka supervisor takes `:security`, the key of a SASL or client certificate scheme of the
Kafka servers, whose brod configuration `<Root>.Kafka.Security` returns with the credentials of
environment variables named after the scheme key (`KAFKA_SCRAM_USERNAME` and
`KAFKA_SCRAM_PASSWORD`; `KAFKA_MTLS_CERT`, `KAFKA_MTLS_KEY` and `KAFKA_MTLS_CA`), as in
[`apigenie-generator server
phoenix`](/docs/reference/generator/server-phoenix-asyncapi#kafka-security). Avro payloads are
structs of their records, encoded and decoded without dependencies, with the ids of their schemas
from a Confluent-compatible registry (the `:schema_registry` option), as in [`apigenie-generator
server phoenix`](/docs/reference/generator/server-phoenix-asyncapi#avro-payloads).

Not supported, and reported as warnings: payloads of non-JSON schema formats other than Avro, Avro
unions other than nullable types and decimals, request/reply operations with Avro messages, reply
addresses given by runtime expressions, Kafka topics with parameters, WebSocket addresses whose
segments mix text and parameters, and security schemes a WebSocket handshake can't carry. Channels
of other protocols (MQTT, AMQP, HTTP) are out of scope. The models check the schemas' constraints,
`if`/`then`/`else`, `dependentRequired`, `dependentSchemas` and `not` when they decode a payload.

## Options

### -c, --config

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

### --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 library is generated.

### --package-name

Name of the Mix application, converted to snake_case (`carpet-express-events` gives
`carpet_express_events`, root module `CarpetExpressEvents`); defaults to the title of the API.
Its kebab case is the base of default group ids.

### --package-version

Version of the Mix project; 0.1.0 by default.

### -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
elixir`; its other keys configure the generation from OpenAPI documents.

```yaml
version: '1.0'
commands:
  generate:
    client_elixir:
      asyncapi:
        app: carpet_express_events
        perspective: counterpart
```

| Option | Type | Default | Description |
| ------ | ---- | ------- | ----------- |
| `app` | string | from `--package-name` or the title | Name of the Mix application (snake_case) |
| `namespace` | string | the application in PascalCase | Root module of the generated modules |
| `perspective` | `counterpart` \| `application` | `counterpart` | The counterpart of the described application, or the application itself |
| `field_prefix` | string | `field_` | Prefix of struct fields whose property names give no valid name |
| `module_overrides` | map | | Module names of payload schemas, e.g. `ShipmentId: ShipmentRef` |
| `dev_deps` | boolean | `true` | credo and dialyxir as dependencies of the dev and test environments |

## 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 elixir` | ✓ snapshots of 3.0; 41 supported, 0 not yet | ✓ pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) | ✓ 18 of 18 operations pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) |
| Release 0.12.0, `client elixir (application)` | ✓ snapshots of 3.0; 26 supported, 0 not yet, 4 not checked | ✓ pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) | ✓ 18 of 18 operations pass (Erlang/OTP 29 [erts-17.1] [source] [64-bit] [smp:8:8] [ds:8:8:10] [async-threads:1] [jit:ns]; Mix 1.20.4 (compiled with Erlang/OTP 29)) |
| Development version, `client elixir` | ✓ snapshots of 3.0; 41 supported, 0 not yet | runs before a release | runs before a release |
| Development version, `client elixir (application)` | ✓ snapshots of 3.0; 26 supported, 0 not yet, 4 not checked | runs before a release | runs before a release |
