Is there a document available that describes how Phoenix channels are multiplexed into that single web socket? How a datagram/message looks like, what a client/server has to implement at least to be considered conforming to the standard?
I’m aware that I could reverse engineer the protocol from reading Phoenix source code, but I really prefer to have some technical document over code.
This is a good documentation, but I don’t think it’s optimal from the standpoint of a client developer. At least, that was my personal impression back when I was writing an Elixir client. Ultimately, I inspected websocket messages in the browser, and read the Phoenix code (both server and client) to understand the protocol. On the plus side, the protocol is pretty simple, so it didn’t require a lot of work.
I think that a guide for client implementers would be beneficial, probably as a separate page in Phoenix docs. It could be written in a tutorial form, something like: to join a topic send a following message, then the server can reply with x or y, … I don’t think such guide would be long, but it could improve the job of client implementers.
If the team agrees, I’ll be happy to give this a shot, with a caveat that I can’t commit on any deadline.
I know this is a bit old but I was just working on making a C++ client and I basically went through a similar process as sasajuric although I found it was also helpful to read the code in the JS client as a reference implementation. I wound up writing this so I wouldn’t forget what I learned:
I didn’t want to create a new topic for this so I’m just going to revive this one.
Has anyone actually produced what could be considered documentation of the Phoenix protocol? Telling people to read the JS source isn’t really good enough, in my opinion. The JS source is, well, JS source code. Translating it to f.e. Haskell you gain almost nothing from the way it’s written in this object spaghetti JS style and can you really claim JS to be a good, descriptive way to express something like a protocol?
E.g. the built in transports use basically a simple json blob for messages:
So the channel -> transport interface is documented and the websocket/longpolling transport -> client is using json in a particular format.
So what I miss the most is some descriptions for the above listed channel events and when they’re sent/shall be sent, some description about how to handle the different refs in messages and how to handle presence lists/diffs.
I would find this useful as well and would be willing to help contribute to this document. We’ve had some bugs in an internal Dart/Flutter implementation and some of these bugs were due to a misunderstanding int he spec.
A good start would be sample send/receive payloads with informal explanations of what is going on.