asyncapi-rust-ws-template

npm project that converts AsyncAPI into rust websocket client crate

how it works

• 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

how to run terminal command

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 

template input requirement (AsyncAPI)

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

template parameters

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

template output (rust client crate)

The rust code generated by this template has the following structure

• Cargo.toml // using info
• README.md // using info
• src/
  • lib.rs // overall library
  • client/
    • mod.rs
    • ${client}.rs // using servers, channels, operations
  • model/
    • mod.rs
    • ${message}.rs // using message schema with modelina

dev setup installation

install react

npm install react

install typescript transpiler

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

contents

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

design

• 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

TODO

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

recruitment

TypeScript AsyncAPI Template Developer

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:

• typescript, go, python

notes

• 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"

see also

• guilder - Unopinionated Cross-Exchange Crypto Trading Library
• exchange-collection - Crypto Exchange OpenAPI(REST) / AsyncAPI(WS) and Clients
• kucoin-arbitrage - KuCoin Cyclic Arbitrage, in Tokio Rust (legacy)
• typed-websocket - Typed WebsSocket Stream