Proposal: Add is_disconnected property to WebSocket

[ruitcatarino]

Motivation

When handling a WebSocket connection, it’s common to have multiple coroutines interacting with the same connection. For example, one coroutine may handle incoming messages, while another handles error recovery or cleanup. In such scenarios, it's possible for multiple coroutines to attempt to close the WebSocket. This can lead to a RuntimeError if a coroutine attempts to close an already-disconnected WebSocket.

To prevent this, I propose adding an is_disconnected property to the WebSocket class. This property would allow developers to check the connection state before performing actions like close.

Benefits

1. Improved Code Clarity
   Developers can use is_disconnected to explicitly check the state of the WebSocket, avoiding reliance on exceptions for flow control. This results in cleaner, more maintainable code.
2. Concurrency Safety
   In concurrent scenarios, checking is_disconnected before attempting an action reduces the risk of race conditions and redundant operations.
3. Minimal Overhead
   The implementation is straightforward, as it wraps existing WebSocket states (application_state and client_state) into a single, intuitive property.

Consider this scenario (that already happened to me):

• Two coroutines manage a WebSocket connection.
• An error occurs, and both attempt to close the connection.
• Without is_disconnected, one coroutine succeeds, while the other raises a RuntimeError.
  By using is_disconnected, this scenario is easily handled:

if not websocket.is_disconnected:
    await websocket.close()

Implementation

Here’s a simple implementation of the is_disconnected property:

@property
def is_disconnected(self) -> bool:
    return (
        self.application_state == WebSocketState.DISCONNECTED
        or self.client_state == WebSocketState.DISCONNECTED
    )

Conclusion

Maybe this is too specific or maybe even based on a wrong principle or a problem with my app or thinking.
I’d love to hear your thoughts on whether this aligns with the framework’s goals and design.
I would gladly implement this if we want to move forward.

[adriangb]

I feel like this may not be the right answer. For example, we could add ws.close(ignore_if_disconnected=True) or something instead.

[adriangb]

I think it's reasonable to want this feature. I will note that if we had made close() idempotent someone would have complained that it didn't raise an error.

I'd be happy to accept a PR for is_disconnected(), although that may need a bit of design work: does it just check the internal attribute or actively check if the connection is alive. Personally I would prefer close(error_if_already_closed=False) similar to pathlib.Path(...).mkdir(exists_ok=True).

[Kludex]

I think it makes more sense to raise WebSocketDisconnect instead of RuntimeError when the application state is disconnected.

I don't think the flag makes sense.

[ruitcatarino]

@adriangb I completely understand why close() can’t be idempotent, and I agree that raising an error is the right default behavior. I also think your proposed alternative close(error_if_already_closed=False) is a great addition and would provide a clean, explicit way to handle this scenario. I will open an issue/PR and implement this (later today probably).

@Kludex I see your point about raising WebSocketDisconnect instead of RuntimeError when the WebSocket is disconnected, and I’d be happy to implement that change as well. It would make the error more specific and informative, addressing part of the problem.
That said, I still believe it would be helpful to provide either a way to proactively check the WebSocket state (via an is_disconnected property) or a flag to ensure that close() can always be called gracefully (like @adriangb suggested).

[Kludex]

I believe the exception is the way to go.