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 :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. 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.

ResultsLevel 1Level 2Level 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 yetruns before a releaseruns before a release
Development version, client elixir (application)✓ snapshots of 3.0; 26 supported, 0 not yet, 4 not checkedruns before a releaseruns before a release
Was this helpful?