Create a simple WebSocket interface

[brianquinlan]

• This just defines the interface that will be implemented using dart:io, package:web and package:cupertino_http.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[brianquinlan]

This Stream and its relationship with the sendText/sendBytes/close methods is my biggest concern with this API.

As documented now, sendText, etc. throw if the WebSocket is closed. But the ClosedReceived event is delivered asynchronously so you can't rely on it being delivered in time to prevent those calls. For example:

timer = Timer.periodic(const Duration(seconds: 2), (timer) {
  websocket.sendText('<stock>GOOG</stock>');
});

await for (final event in websocket.events) {
  switch (event) {
  // Should probably do something with the stock quote.
  case CloseReceived:
    // This is not sufficient - the implementation may add `CloseReceived` to the `StreamController` and then
    // close the `StreamController` before this event is received. This probably means that, in practice, every
    // call to `sendText`/`sendBytes` will need to be guarded in a `try`/`catch`
    timer.cancel();
  }
}

Some alternatives:

1. just throw away sendText/sendBytes after the WebSocket is closed - this is what JavaScript does
2. use SyncStreamController (will that work?)
3. make a synchronous callback for events instead of using a Stream.

[natebosch]

I think even if we synchronously surface a ClosedReceived there is still the possibility of a sendText failing to write because of a closed socket, though it may be significantly less less likely.

I would probably start with throwing, and we can consider an option to silently discard if that has a clear use case.

[brianquinlan]

I think even if we synchronously surface a ClosedReceived there is still the possibility of a sendText failing to write because of a closed socket, though it may be significantly less less likely.

My plan was for sendText/sendBytes to not throw in that case. Any other behavior would be difficult on the web, which only allows send to throw if the connection isn't established.

I have a conformance test to verify that behavior (the tests are still very rough at this point).

I've updated the docs to make a note of that.

I would probably start with throwing, and we can consider an option to silently discard if that has a clear use case.

SGTM!

[natebosch]

I think even if we synchronously surface a ClosedReceived there is still the possibility of a sendText failing to write because of a closed socket, though it may be significantly less less likely.

I would probably start with throwing, and we can consider an option to silently discard if that has a clear use case.