What's New in 1.3¶
1.3 adds WebSocket endpoints to application units. Existing code needs no changes.
For earlier releases, see What's New in 1.2, What's New in 1.1 and What's New in 1.0.
WebSocket endpoints¶
@websocket marks a method as a WebSocket endpoint, written in the same router as HTTP
endpoints:
from canary_framework import Canary, dep, init
from canary_framework.web.asgi.app import App, HTTPError, Router, WebSocket, get, websocket
from canary_framework.web.asgi.server import Server
class Rooms(Canary):
@init
def open(self) -> None:
self.log: dict[str, list[str]] = {}
class RoomApi(Router, prefix="/rooms"):
rooms = dep(Rooms)
@get("/{room}")
async def history(self, room: str) -> list[str]:
return self.rooms.log.get(room, [])
@websocket("/{room}")
async def chat(self, socket: WebSocket, room: str, name: str) -> None:
if not name.isidentifier():
raise HTTPError(403, "bad name") # before the handshake: the client gets 403
async for message in socket: # ends normally when the client leaves
self.rooms.log.setdefault(room, []).append(f"{name}: {message}")
await socket.send(f"{name}: {message}")
class ChatApi(App):
rooms = dep(RoomApi)
class Gateway(Server):
api = dep(ChatApi)
port = 8010
- Path and query parameters are bound and validated as for HTTP endpoints; a parameter
annotated
WebSocketis the connection itself. - The handshake is accepted on the first receive or send. A failure before it — no matching
path, a failed validation, an
HTTPError— is answered with the same error response as over HTTP; after it, anHTTPErrorcloses with 1008 and anything else closes with 1011 and is logged. - One path may have both an HTTP endpoint and a WebSocket endpoint.
See Web application › WebSocket for the details.
Worth knowing¶
These show only once you use WebSocket:
- WebSocket endpoints appear in
App.endpointswith the method"WEBSOCKET". Code that writes OpenAPI from that table should skip them; the example under the endpoint table now does. - A WebSocket connection to an application unit with no matching WebSocket endpoint used to be closed with 1008 (the client saw 403); it is now answered with 404 where the server supports it.
canary-framework[server]now installswsproto, and the server unit uses it for WebSocket by default. Web server says why.
Also in 1.3¶
- Why Canary is re-measured with 1.2.0; the Canary column is unchanged.
- The full list is in the changelog.