investigate representing #[channel] in AsyncAPI format #429
Comments
lifning
pushed a commit
to lifning/progenitor
that referenced
this issue
Aug 31, 2022
rel: oxidecomputer/dropshot#403 Generated methods return a `WebsocketReactants` type that at present can only be unwrapped into its inner `http::Request` and `tokio::net::TcpStream` for the purpose of implementing against the raw websocket connection, but may later be extended as a generic to allow higher-level channel message definitions (rel: oxidecomputer/dropshot#429) The returned `Request` is an HTTP request containing the client's part of the handshake for establishing a Websocket, and the `TcpStream` is a raw TCP (non-Web-) socket. The consumer of the raw `into_request_and_tcp_stream` interface is expected to send the HTTP request over the TCP socket, i.e. by providing them to a websocket implementation such as `tokio_tungstenite::client_async(Request, TcpStream)`.
lifning
pushed a commit
to lifning/progenitor
that referenced
this issue
Aug 31, 2022
rel: oxidecomputer/dropshot#403 Generated methods return a `WebsocketReactants` type that at present can only be unwrapped into its inner `http::Request` and `tokio::net::TcpStream` for the purpose of implementing against the raw websocket connection, but may later be extended as a generic to allow higher-level channel message definitions (rel: oxidecomputer/dropshot#429) The returned `Request` is an HTTP request containing the client's part of the handshake for establishing a Websocket, and the `TcpStream` is a raw TCP (non-Web-) socket. The consumer of the raw `into_request_and_tcp_stream` interface is expected to send the HTTP request over the TCP socket, i.e. by providing them to a websocket implementation such as `tokio_tungstenite::client_async(Request, TcpStream)`.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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?)
The text was updated successfully, but these errors were encountered: