Safe Haskell	Safe-Inferred
Language	Haskell2010

Network.Simple.WSS

Contents

Sending and receiving
Client side
Low level

Description

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.

Synopsis

data Connection
recv :: MonadIO m => Connection -> m (Either (Word16, ByteString) ByteString)
send :: MonadIO m => Connection -> ByteString -> m ()
close :: MonadIO m => Connection -> Word16 -> ByteString -> m ()
connect :: (MonadIO m, MonadMask m) => ClientParams -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr) -> m r) -> m r
connectOverSOCKS5 :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> ClientParams -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr, SockAddr) -> m r) -> m r
clientConnectionFromStream :: MonadIO m => Stream -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> m Connection
streamFromContext :: MonadIO m => Context -> m Stream

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 Source #

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 Source #

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 Source #

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