Spec question: `websocket.disconnect` doesn't support the `reason` field

[frankie567]

From the WebSocket specification, it's possible to set a "reason" when either the server or the client closes the connection: https://datatracker.ietf.org/doc/html/rfc6455#section-7.1.6

In the ASGI specification, this is well supported for the "Close - send event" (i.e. close sent by the server):

asgiref/specs/www.rst

Lines 476 to 496 in db3ff43

	Close - ``send`` event
	''''''''''''''''''''''
	Sent by the application to tell the server to close the connection.
	If this is sent before the socket is accepted, the server
	must close the connection with a HTTP 403 error code
	(Forbidden), and not complete the WebSocket handshake; this may present on some
	browsers as a different WebSocket error code (such as 1006, Abnormal Closure).
	If this is sent after the socket is accepted, the server must close the socket
	with the close code passed in the message (or 1000 if none is specified).
	* ``type`` (*Unicode string*) -- ``"websocket.close"``.
	* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket
	spec. Optional; if missing defaults to ``1000``.
	* ``reason`` (*Unicode string*) -- A reason given for the closure, can
	be any string. Optional; if missing or ``None`` default is empty
	string.

However, for the "Disconnect - receive event (i.e. close sent by the client), it is not supported; only the code can be set:

asgiref/specs/www.rst

Lines 440 to 458 in db3ff43

	Disconnect - ``receive`` event
	''''''''''''''''''''''''''''''
	Sent to the application when either connection to the client is lost, either from
	the client closing the connection, the server closing the connection, or loss of the
	socket.
	Once you have received this event, you should expect future calls to ``send()``
	to raise an exception, as described below. However, if you have highly
	concurrent code, you may find calls to ``send()`` erroring slightly before you
	receive this event.
	Keys:
	* ``type`` (*Unicode string*) -- ``"websocket.disconnect"``
	* ``code`` (*int*) -- The WebSocket close code, as per the WebSocket spec. If no code
	was received in the frame from the client, the server should set this to ``1005``
	(the default value in the WebSocket specification).

Is there a particular reason to omit this field for this particular event?

[andrewgodwin]

I do not remember a specific reason; it was likely either an oversight or the libraries I developed the spec against last decade didn't support it.

[frankie567]

Thank you for your feedback 🙂 Then, do you see any inconvenience if I propose a PR to add this to the spec?

[Kludex]

Can you give me some days to reply here? I'm on vacation, but I'm back next week.

[frankie567]

Sure! Enjoy your holidays 🌴

[frankie567]

Hey @Kludex 👋 Did you have some time to think about this? 🙂

[Kludex]

It looks like an oversight, but... No one complained in years... Do you need it?

[frankie567]

Well, not a really big issue but yes, I had one complain downstream in httpx-ws. Relevant context:

• `WebSocketDisconnectEvent` is not handling the `reason` field encode/uvicorn#2299
• Can't send close reason correctly frankie567/httpx-ws#70

IMHO, it looks like a harmless addition that would make the spec a bit more compliant regarding WS spec. Happy to make the PR, if you agree 🙂

[Kludex]

Do the WebSockets clients send the "reason"?

[frankie567]

They can, if I understand correctly the spec. It's apparently supported by browsers API: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/close

[Kludex]

Then I don't mind adding it.