Safe Haskell	Safe-Inferred
Language	Haskell2010

Network.Simple.WS

Contents

Sending and receiving
Client side
Low level

Description

Simple tools for establishing and using insecure WebSockets connections on top of TCP (i.e, ws://).

See the network-simple-wss package for Secure WebSockets (i.e, wss://) 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) => HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr) -> m r) -> m r
connectSOCKS5 :: (MonadIO m, MonadMask m) => HostName -> ServiceName -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> ((Connection, SockAddr, SockAddr) -> m r) -> m r
clientConnectionFromStream :: MonadIO m => Stream -> HostName -> ServiceName -> ByteString -> [(ByteString, ByteString)] -> m Connection
streamFromSocket :: MonadIO m => Socket -> m Stream

Sending and receiving

data Connection #

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

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

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

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)
=> 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==")]`).
-> ((Connection, SockAddr) -> m r)	Computation to run after establishing a WebSockets to the remote server. Takes the WebSockets `Connection` and remote end address.
-> m r

Connect to the specified WebSockets server.

connectSOCKS5 Source #

Arguments

:: (MonadIO m, MonadMask m)
=> HostName	SOCKS5 proxy server hostname or IP address.
-> ServiceName	SOCKS5 proxy server service port name or number.
-> HostName	Destination 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 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 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 Source #

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.

streamFromSocket :: MonadIO m => Socket -> m Stream Source #

Obtain a Stream implemented using the network Socket. You can use the network-simple library to get one of those.