WebSockets support

[florimondmanca]

Is your feature request related to a problem? Please describe.
WebSockets enable a whole set of real-time web applications, which look like great candidates for async web servers. It should be as easy to build a backend websocket server than it is to create a websocket client in the frontend world.

Describe the solution you'd like
Implement a friendly, async/await-based interface for building websocket views, which would allow to write something like:

import json
from bocadillo import API, WebSocket

api = API()

@api.websocket_route("/chat", value_type="json")
async def chat(ws: WebSocket):
    async with ws:
        # The connection has been accepted.
        async for message in ws:
            await ws.send({"type": "echo", "message": message})
        # Connection closes when leaving this block.
    # The client has disconnected normally. Perform extra cleanup if needed.

• The async for syntax should just be a shortcut for a while True loop that repeatedly calls receive_<value_type>() on the WebSocket object.
• The async with syntax allows to automatically accept() and close() the WebSocket.
  • It should catch Disconnect exceptions with normal close codes (1000 or 1001).
  • It should be possible to customize which close codes are silenced, e.g. with a caught_close_codes: Tuple[int] argument.
  • In case of an unknown exception, the connection should be closed with a 1011 (Unexpected Error) code.
• value_type=X is a shortcut for receive_type=X, send_type=X. Possible values are ["text", "json", "bytes", "event"].

Note: with the syntax above, hooks do not have to be ported to WebSockets. The developer can perform any operation before/after the context enters/exits.

For the implementation, this feature should mostly be a wrapper around Starlette WebSockets.

Describe alternatives you've considered

• Starlette's WebSocketEndpoint uses a callback style which is not consistent with the rest of the Bocadillo API.

Additional context
Came to this conclusion while thinking about example projects for a tutorial. :)

[cs01]

I just created an issue to bring bocadillo+async+await to pyxterm.js (cs01/pyxtermjs#3). If I (or someone else) implements it, it would be a great project to demonstrate Bocadillo since it's a small project but a really interesting experience of having a working terminal in the browser.

[florimondmanca]

@cs01 Thanks for the heads up! I was interested in that thumbsup you left on the issue, my questions are now answered. ;-) Looking forward to seeing Bocadillo + WebSockets in action in pyxterm.js once we roll this feature out. 👍

[cs01]

In the back of my mind I was thinking of using it on https://github.com/cs01/gdbgui since it has a similar architecture, but that would be a much bigger undertaking. I realized today that a good first step would be pyxterm.js.

[florimondmanca]

Yep, that's a smart move. Better to start with a proof of concept than putting the stability of a 6k+ star project at risk.

[florimondmanca]

@cs01 Bocadillo WebSockets are now a thing! Will release 0.9 soon.

[cs01]

Great work, can’t wait to try it out.

[florimondmanca]

Update: v0.9 has just been released 😉 https://pypi.org/project/bocadillo/0.9.0