Need HTTP.WebSockets documentation

Laszlo_Nagy · May 10, 2020, 6:27pm

Hello, I’m trying to do something useful with websockets. I’m unable to find its documentation.

julia> import HTTP.WebSockets

help?> HTTP.WebSockets
  No documentation found.

  No docstring found for module HTTP.WebSockets.

Not even a docstring.

There two examples here GitHub - JuliaWeb/HTTP.jl: HTTP for Julia - but they don’t really explain anything. For example, websockets use so called messages, as defined in RFC6455. But the example does not use that concept. It just reads from the socket (as a stream with readavailable) and writes it as a stream. After examinig its source code, it turned out that readavailable reads whole frames.

github.com

JuliaWeb/HTTP.jl/blob/master/src/WebSockets.jl#L239


      
              message::Union{String, CloseFrameBody}
          end
          
          
"""
              WebSockets.isok(x::WebSocketError) -> Bool
          
          
Returns true if the `WebSocketError` has a non-error status code.
          When calling `receive(websocket)`, if a CLOSE frame is received,
          the CLOSE frame body is parsed and thrown inside the `WebSocketError`,
          but if the CLOSE frame has a non-error status code, it's safe to
          ignore the error and return from the `WebSockets.open` or `WebSockets.listen`
          calls without throwing.
          """
          isok(x) = x isa WebSocketError && x.message isa CloseFrameBody && (x.message.status == 1000 || x.message.status == 1001 || x.message.status == 1005)
          
          
"""
              WebSocket(io::HTTP.Connection, req, resp; client=true)
          
          
Representation of a websocket connection.
          Use `WebSockets.open` to open a websocket connection, passing a
          handler function `f(ws)` to send and receive messages.

Can I assume, that readavailable will always return whole messages, and never fragments?

Also, it seems that there is no upper limit on the message size, and WebSockets.jl simply extends a read buffer (ws.rxpayload) when the message is longer. Since the payload is stored in memory, it would be easy to fill up the server’s memory with a huge message. Is this a known problem? Or maybe I’m not noticing something.