WebSocket data frame streaming

[adam-fowler]

Adding methods to stream WebSocket messages inbound and outbound.

Inbound

By default WebSocketInboundStream is now a stream of fragmented WebSocket data frames. You can convert this to a stream of WebSocket messages using WebSocketInboundStream.messages(maxSize:). eg

for try await message in inbound.messages(maxSize: 1024) {
    ...
}

You can also extract a single complete message from an inbound iterator using

var inboundIterator = inbound.makeAsyncIterator()
let msg = try await inboundIterator.nextMessage(maxSize: 1024)

Outbound

Two new functions have been added to WebSocketOutboundWriter: withTextMessageWriter(:_) and withBinaryMessageWriter(:_). With these you can write a single message across fragmented frames.

try await outbound.withTextMessageWriter { writer in
    try await writer("Merry Christmas ")
    try await writer("and a ")
    try await writer("Happy new year")
}

[Joannis]

I like this a lot, since we can now also decode a frame.opcode == .text into JSON without having to do the dance of converting to String inbetween. Because currently, we'd need to convert ByteBuffer into String, then into Data again.

[adam-fowler]

It is like this because a single frame fragment can have incomplete UTF8 data, so we can't decode it until we have all the frames that make up a message.

Unfortunately the WebSocketMessage text case is a String. Should I consider changing that back to a ByteBuffer.

[Joannis]

This could leverage the same writer mentioned above, but the writer would store the expected opcode. I think it's valid to send a String over a binary WebSocket message.

[adam-fowler]

done

[tkrajacic]

I like it

[tkrajacic]

I am not 100% certain this logic is correct.
frame.opcode == .continuation might be set for a message with a yet unknown (non-control-frame) opcode, that is not text or binary and defined in an extension. The check for text or binary is somewhat incompatible with this condition, as now we include continuations of other types (excluding their initial frames)

See https://www.rfc-editor.org/rfc/rfc6455.html#section-5.4

Wouldn't we need to keep track of the opcode that the current continuation pertains to?

Then again… one could argue that we don't implement the ability to handle any other opcodes, and would error out earlier, so this is fine.

[adam-fowler]

Are there any particular unknown opcodes that have associated application data? If not then the only ones known are binary, text and continuation. And a continuation only appears once we have received a data or text.

[adam-fowler]

Deflate doesn't care if a frame is text or binary.

[tkrajacic]

Nah, you are right. we need to close the connection anyway if there are unknown opcodes.