Asyncapi-rust-ws-template NPM

asyncapi-rust-ws-template

npm project that converts AsyncAPI into rust websocket client crate

npm version

exchange name is provided
goes through each doc -> server -> channel, each serving as a websocket stream
goes through each channel's send/receive operation, map their messages and payloads as stream input/output
union payload gets converted as enum
gets rendered with string operations

npm build, local YAML

$ asyncapi generate fromTemplate ASYNCAPI_DIR asyncapi-rust-ws-template -p exchange=EXCHANGE_NAME -o OUTOUT_DIR

local build, local YAML (at the root of this project)

$ ag ASYNCAPI_DIR ./ -o OUTPUT_DIR

spec	requirement
format	AsyncAPI v3 (pls check notes for its reason)
point of view	client (send request, receive reponse)
minimum content requirement for WS client	`info`, `servers`, `channels`, `components` , can be tested with `-p validate=true`

parameter	options	description
`validate`	`true` `false (default)`	to validate if a AsyncAPI has minimum content for generating websocket client
`render`	`true` `false (default)`	to render a rust websocket client
`framework`	`tokio-tungstenite (default)`, `async-tungstenite`	rust websocket client framework to render

The rust code generated by this template has the following structure

install react

npm install react

install typescript transpiler

npm install @types/react --save-devnpm install typescript @types/node --save-dev

name	description
src/	TypeScript ESM source code, transpiles into `template` directory
src/index.ts	transpiles to main template entry `template/index.js`, exposing the function for `asyncapi generator` command
hooks/	AsyncAPI hooks for pre-process and post-process that cannot be derived by AsyncAPI (in CommonJS)
template/	Javascript transcribed source code for template
test/input	local test input, AsyncAPI document
test/output	local test output, rust client crate (git-ignore)
package.json	NPM package definition, defines template configs
tsconfig.json	TypeScript transpile definition, defined transcribed datas
CHANGELOG	change log

renderer:
- react rather than nunjucks, for its versatility. details here
- TypeScript, ESM (except hooks)
generated code are derived as below:
- client (server)
- client function (channel)
- client function logic (operation)
- client function struct (schema)
client code functionality:
- case 1: subscribe
- case 2: publish, subscribe

changelog: please check here

design codegen structure
- study nunjucks vs react (decided to use react)
code generation
- define code structure
- websocket client function from operation
- pubsub function from channel
- fix modelina referencing other model as crate::*;
code testing
- add unit test
- make server name configurable
- loads server name into unit test
support N messages on an operation
check for cases when one channel supports multiple inputs
support for async-tungstenite

I am not a TS expert, so I would love to have an expert to accelarate development for websocket genrator in the following output languages:

changelog here
support AsyncAPI V3 only because official v2 and v3 terminology on AsyncAPI are flipped.
- v2 calls operations "publish", "subscribe" from client's perspective
- v3 calls operations "receive", "send" from server's perspective
- this is objectively confusing, so make sure the input is an AsyncAPI V3 on client's perspective, which follows "send request, receive response"