apigenie-generator client elixir (AsyncAPI)
Tier 2 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification
Generate an Elixir client library of the WebSocket and Kafka channels of an AsyncAPI document.
Usage
apigenie-generator client elixir [...OPTIONS] INPUT_FILE
Description
apigenie-generator client elixir generates from OpenAPI documents (see
apigenie-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,
the Kafka channels use 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, 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.
{: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:urland joins the channel. Withframing: :phoenix, the default, it speaks the Phoenix Channels protocol (version 2) ofapigenie-generator server phoenix: the socket/socket/websocket, the channel’s topic (the address segments joined by:), the ws binding’s:queryas the join payload, a heartbeat every 30 seconds. Withframing: :plainit 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’sHandlerbehaviour (the:handleroption), or sent to the calling process.:headersare the headers of the channel’s ws binding, sent with the handshake. - WebSocket security.
:credentialsmaps the keys of the channel’s security schemes to credentials, andconnectsends 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,httpbearer) as theaccess_tokenquery parameter in the Phoenix framing and as theAuthorizationheader 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>/1checks a message’s headers and returns once the brokers have the record;request_<message>/2waits 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, asserver phoenixdoes: told apart by a constant header (ce_type), payload property or decoding, with the optionalon_unknown/1andon_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. 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.
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.
-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.
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 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 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 |