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

• [x] design codegen structure
  • [x] study nunjucks vs react (decided to use react)
• [x] code generation
  • [x] define code structure
  • [x] websocket client function from operation
  • [x] pubsub function from channel
  • [x] fix modelina referencing other model as crate::*;
• [x] code testing
  • [x] add unit test
  • [x] make server name configurable
  • [x] loads server name into unit test
• [x] support N messages on an operation
• [x] 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