Skip to content

Commit

Permalink
Clarify send error behaviour more clearly
Browse files Browse the repository at this point in the history
  • Loading branch information
andrewgodwin committed Feb 2, 2024
1 parent 0503c2c commit 6f02daa
Showing 1 changed file with 30 additions and 1 deletion.
31 changes: 30 additions & 1 deletion specs/www.rst
Original file line number Diff line number Diff line change
Expand Up @@ -241,9 +241,13 @@ Disconnected Client - ``send`` exception
''''''''''''''''''''''''''''''''''''''''

If ``send()`` is called on a closed connection the server should raise
a server-specific subclass of ``IOError``.
a server-specific subclass of ``IOError``. This is not guaranteed, however,
especially on older ASGI server implementations (it was introduced in spec
version 2.4).

Applications may catch this exception and do cleanup work before
re-raising it or returning with no exception.

Servers must be prepared to catch this exception if they raised it and
should not log it as an error in their server logs.

Expand All @@ -256,6 +260,11 @@ sent or after the HTTP connection has been closed. This is mainly useful
for long-polling, where you may want to trigger cleanup code if the
connection closes early.

Once you have received this event, you should expect future calls to ``send()``
to raise an exception, as described above. However, if you have highly
concurrent code, you may find calls to ``send()`` erroring slightly before you
receive this event.

Keys:

* ``type`` (*Unicode string*) -- ``"http.disconnect"``.
Expand Down Expand Up @@ -435,6 +444,11 @@ Sent to the application when either connection to the client is lost, either fro
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"``
Expand All @@ -444,6 +458,21 @@ Keys:
(the default value in the WebSocket specification).


Disconnected Client - ``send`` exception
''''''''''''''''''''''''''''''''''''''''

If ``send()`` is called on a closed connection the server should raise
a server-specific subclass of ``IOError``. This is not guaranteed, however,
especially on older ASGI server implementations (it was introduced in spec
version 2.4).

Applications may catch this exception and do cleanup work before
re-raising it or returning with no exception.

Servers must be prepared to catch this exception if they raised it and
should not log it as an error in their server logs.


Close - ``send`` event
''''''''''''''''''''''

Expand Down

0 comments on commit 6f02daa

Please sign in to comment.