Network.Simple.WSS

Simple tools for establishing and using Secure WebSockets connections on top of TLS (i.e, wss://).

See the network-simple-ws package for insecure WebSockets (i.e, ws://) support.

Notice that, currently, this is package offers tools that are mostly intreresting from a client's point of view. Server side support will come later.

Sending and receiving

data Connection

recv :: MonadIO m => Connection -> m (Either (Word16, ByteString) ByteString)

Receive a single full WebSockets message from the remote end as a lazy ByteString (potentially empty).

Throws IOException if there is an unexpected Connection error.

If the remote end requested the Connection to be closed, then Left will be returned instead, with a close code and reason description.

• See https://datatracker.ietf.org/doc/html/rfc6455#section-7.4 for details about the close codes.
• Do not use recv after receiving a close request.
• If you receive a close request after after having sent a close request yourself (see close), then the WebSocket Connection is considered closed and you can proceed to close the underlying transport.
• If you didn't send a close request before, then you may continue to use send, but you are expected to perform close as soon as possible in order to indicate a graceful closing of the connection.

send :: MonadIO m => Connection -> ByteString -> m ()

Send a lazy ByteString (potentially empty) to the remote end as a single WebSockets message, in potentially multiple frames.

If there is an issue with the Connection, an exception originating from the underlying Stream will be thrown.

close

Arguments

:: MonadIO m

=> Connection

-> Word16

Close code.

-> ByteString

Reason for closing.

-> m ()

Send a close request to the remote end.

After sending this request you should not use send anymore, but you should still continue to call recv to process any pending incomming messages. As soon as recv returns Left, you can consider the WebSocket Connection closed and can proceed to close the underlying transport.

If there is an issue with the Connection, an exception originating from the underlying Stream will be thrown.

Client side

connect

Arguments

:: (MonadIO m, MonadMask m)

=> ClientParams

TLS settings.

-> HostName

Secure WebSockets server host name (e.g., "www.example.com" or IP address).

-> ServiceName

Secure WebSockets server port (e.g., "443" or "www").

-> ByteString

Secure WebSockets resource (e.g., "/foo/qux?bar=wat&baz").

Leading '/' is optional.

-> [(ByteString, ByteString)]

Extra HTTP Headers (e.g., [("Authorization", "Basic dXNlcjpwYXNzd29yZA==")]).

-> ((Connection, SockAddr) -> m r)

Computation to run after establishing a Secure WebSockets to the remote server. Takes the WebSockets connection and remote end address.

-> m r

Connect to the specified Secure WebSockets server.

connectOverSOCKS5

Arguments

:: (MonadIO m, MonadMask m)

=> HostName

SOCKS5 proxy server hostname or IP address.

-> ServiceName

SOCKS5 proxy server service port name or number.

-> ClientParams

TLS settings.

-> HostName

Destination Secure WebSockets server hostname or IP address. We connect to this host through the SOCKS5 proxy specified in the previous arguments.

Note that if hostname resolution on this HostName is necessary, it will happen on the proxy side for security reasons, not locally.

-> ServiceName

Destination Secure WebSockets server port (e.g., "443" or "www").

-> ByteString

WebSockets resource (e.g., "/foo/qux?bar=wat&baz").

Leading '/' is optional.

-> [(ByteString, ByteString)]

Extra HTTP Headers (e.g., [("Authorization", "Basic dXNlcjpwYXNzd29yZA==")]).

-> ((Connection, SockAddr, SockAddr) -> m r)

Computation taking a Connection for communicating with the destination Secure WebSockets server through the SOCKS5 server, the address of that SOCKS5 server, and the address of the destination WebSockets server, in that order.

-> m r

Like connect, but connects to the destination server through a SOCKS5 proxy.

Low level

clientConnectionFromStream

Arguments

:: MonadIO m

=> Stream

Stream on which to establish the WebSockets connection.

-> HostName

WebSockets server host name (e.g., "www.example.com" or IP address).

-> ServiceName

WebSockets server port (e.g., "443" or "www").

-> ByteString

WebSockets resource (e.g., "/foo/qux?bar=wat&baz").

Leading '/' is optional.

-> [(ByteString, ByteString)]

Extra HTTP Headers (e.g., [("Authorization", "Basic dXNlcjpwYXNzd29yZA==")]).

-> m Connection

Established WebSockets connection

Obtain a Connection to the specified URI over the given Stream, connected to either a WebSockets server, or a Secure WebSockets server.

streamFromContext :: MonadIO m => Context -> m Stream

Obtain a Stream implemented using the given TLS Context. You can use the network-simple-tls library to get one of those.