Documentation of required headers/params for websocket streaming is incorrect

[daprice]

In the docs under WebSocket > Parameters the required parameters/headers are incorrect:

• the Authorization header is marked as required, but in reality you can also provide the user token in the Sec-WebSocket-Protocol header (which the documentation omits) as an alternative to Authorization
• the access_token param is marked as required, but in reality it is only needed if you don’t use either of the aforementioned headers (and maybe should be recommended against because some network stacks might log the full URL string to disk and leak the access token)
• the stream param is marked as required, but it isn’t required in reality. You can instead open a “blank” websocket without any particular stream, and then send subscribe message(s) for the stream(s) you want over the websocket after it is open.

Lastly:

• The WebSocket protocol allows payloads to be sent as either plain text or binary, but the Mastodon documentation of the JSON subscribe/unsubscribe payloads doesn’t specify which it expects. In practice it only seems to accept plain text. This might not be obvious to client developers because some frameworks like Swift Foundation treat encoded JSON as binary data by default.

[mjankowski]

I believe the linked issues deal with the auth header, sec-websocket-protocol header, access_token param, and text/binary aspects of this.

The "stream param claims to be required" part is not done yet. That entire section is a little ambiguous around the "basic establishing connection" portions and the "specific stream interactions" portions. May have to shuffle a bit.