oxidecomputer / oxidecomputer/dropshot

investigate representing #[channel] in AsyncAPI format

Open
#429 0 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
1.2k
Forks
104
Avg merge
1d 19h
Merged PRs (30d)
22

Description

Currently the #[channel] annotation used for declaring WebSocket endpoints simply places a "x-dropshot-websocket" extension in the generated OpenAPI spec endpoint.
We might consider instead representing these in AsyncAPI schema, an OpenAPI-derived format for describing APIs using protocols unsupported by OpenAPI, including WebSockets.

This would enable us to add support for defining message formats in the macro, and generating a tagged-enum wrapper with progenitor, for example.
Our current use cases for websocket channels in our APIs are for shunting packets of existing binary protocols -- serial console and websocket -- to a web client.
As a result, it's unclear if it's worth taking on all this message complexity of explicitly defining higher-level contents of "messages" for what we're shipping in the near-term, but it would be nicer for the purpose of continuing to support existing web service community standards such that tooling for other languages can generate clients for our APIs.

(relatedly: do we want a general process for graduating any one-off extensions we develop into appropriate community standards where/when they exist?)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the #[channel] annotation and the generated OpenAPI endpoint extension. Read the referenced AsyncAPI message-object specification and consider how progenitor would consume a generated tagged-enum wrapper. Done would require a clearly scoped decision or implementation plan for representing WebSocket channels and message formats; the issue names no files or tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.