Expose HTTP Response Headers in WebSocket.connect Result

[dickermoshe]

The WebSocket.connect method in Dart's dart:io library (or related packages like web_socket_channel) currently returns a WebSocket object upon successful connection, but it does not provide access to the underlying HTTP response headers from the initial handshake.

t would be nice to get the headers of the initial request that was sent. Maybe even the actual response object. This would allow developers to inspect both sides of the handshake for debugging, validation, and integration purposes.

Proposed Solution

Modify WebSocket object to contain a field that has the HttpResponse (or at least its headers via HttpHeaders). This would mirror how HTTP clients like HttpClient expose response details.

Suggested API change:

Modify the WebSocket object to include a new property (e.g., headers or handshakeResponse) that exposes an HttpResponse object (or at least its HttpHeaders for the response). This would align with Dart's HTTP ecosystem, where HttpClient already provides detailed response access.

class WebSocket {
// Existing fields...

/// The HTTP response from the handshake, including headers and status.
final HttpResponse? handshakeResponse;

/// Or, for a lighter option: just the headers.
final HttpHeaders headers; // Could include both request and response if differentiated.
}

Use Case

This feature is particularly useful for clients like the Convex client library, where connecting with an older version of the library causes the server to send deprecation messages in the headers of the initial WebSocket response. Currently, there's no way to access these headers programmatically after the connection is established, preventing developers from reading, logging, or acting on these warnings (e.g., prompting users to update).

[biggs0125]

@brianquinlan mentioned that this would not work on several platforms because the underlying transport layer is not available. This would only work for dart:io but we don't want to create divergent behavior here.

Using a separate tool (e.g. wireshark or the chrome network inspector) to analyze the transport layer could be a workaround here.