0.3.2 • Published 8 months ago

asyncapi-rust-ws-template v0.3.2

Weekly downloads
-
License
MIT
Repository
github
Last release
8 months ago

AsyncAPI logo

asyncapi-rust-ws-template

npm project that converts AsyncAPI into rust websocket client crate

npm version license discord

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)

specrequirement
formatAsyncAPI v3 (pls check notes for its reason)
point of viewclient (send request, receive reponse)
minimum content requirement for WS clientinfo, servers, channels, components , can be tested with -p validate=true

template parameters

parameteroptionsdescription
validatetrue false (default)to validate if a AsyncAPI has minimum content for generating websocket client
rendertrue false (default)to render a rust websocket client
frameworktokio-tungstenite (default), async-tungsteniterust 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

namedescription
src/TypeScript ESM source code, transpiles into template directory
src/index.tstranspiles 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/inputlocal test input, AsyncAPI document
test/outputlocal test output, rust client crate (git-ignore)
package.jsonNPM package definition, defines template configs
tsconfig.jsonTypeScript transpile definition, defined transcribed datas
CHANGELOGchange 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

0.3.2

8 months ago

0.3.1

8 months ago

0.3.0

10 months ago

0.2.3

10 months ago

0.2.4

10 months ago

0.2.1

11 months ago

0.2.2

11 months ago

0.2.0

11 months ago

0.1.4

11 months ago

0.1.3

11 months ago

0.1.2

11 months ago

0.1.1

11 months ago