Control.Monad.Trans.Connect

Simple monad transformer allowing your monad stack to manage a single TCP connection, optionally over TLS and/or SOCKS.

Connect and disconnect

data ConnectT m a

Monad transformer allowing your monad stack to manage a single TCP connection, optionally over TLS and/or SOCKS. A single ConnectT computation sequence opens a connection, possibly sends and receives data, and finally closes it.

Instances

MonadTrans ConnectT

Monad m => Monad (ConnectT m)

Functor m => Functor (ConnectT m)

MonadFix m => MonadFix (ConnectT m)

Applicative m => Applicative (ConnectT m)

MonadThrow m => MonadThrow (ConnectT m)

MonadCatch m => MonadCatch (ConnectT m)

MonadMask m => MonadMask (ConnectT m)

MonadIO m => MonadIO (ConnectT m)

runConnectT

Arguments

:: (MonadIO m, MonadMask m)

=> ConnectT m a

The computation

-> ConnectionParams

Network connection details

-> Bool

Whether to close the connection if the computation finishes without errors (the connection is always closed in case of error unless you catch the error and handle it your way).

-> m a

Execute a computation which has a network connection available to it. If an exception is thrown (e.g. due to network error) and the computation doesn't catch it, the connection is closed and the exception is rethrown.

runConnectTWithCtx :: (MonadIO m, MonadMask m) => ConnectT m a -> ConnectionContext -> ConnectionParams -> Bool -> m a

A variant of runConnectT which takes an existing ConnectionContext instead of initializing a new one. This is useful if you want to start several connections (in which case you can share a single context between them).

connClose :: MonadIO m => ConnectT m ()

Close a connection. After you do that, don't use the connection. If the connection is already closed, for a plain TCP connection this currently does nothing. But when using TLS, it assumes the connection is still open. So to be safe, don't use this more than once.

If you asked for the connection to be closed after a succesful computation (i.e. passed True to runConnectT), then the connection will be closed for you and calling this function is unnecessary (and possibly unsafe).

Receive data

connGetSome :: MonadIO m => Int -> ConnectT m ByteString

Wait until there is data to read from the connection, and return it. The parameter specifies the maximal number of bytes to read. Less than that can be returned, depending on how much data was available.

On end of input, an empty bytestring is returned, but subsequent calls will throw an isEOFError exception.

connGetChunk :: MonadIO m => ConnectT m ByteString

Get the next block of data from the connection.

connGetChunk' :: MonadIO m => (ByteString -> (a, ByteString)) -> ConnectT m a

Like connGetChunk, but return the unused portion to the buffer, where it will be the next chunk read.

connGetLine :: MonadIO m => Int -> ConnectT m ByteString

Get the next line, using ASCII LF ('\n') as the line terminator.

This throws an isEOFError exception on end of input, and LineTooLong when the number of bytes gathered is over the limit without a line terminator.

The actual line returned can be bigger than the limit specified, provided that the last chunk returned by the underlaying backend contains a LF.

An end of file will be considered as a line terminator too, if the line is not empty.

Send data

connPut :: MonadIO m => ByteString -> ConnectT m ()

Send a block of data over the connection.

TLS

connSetSecure :: MonadIO m => TLSSettings -> ConnectT m ()

Activate secure layer using the parameters specified.

This is typically used to negociate a TLS channel on an already establish channel, e.g. supporting a STARTTLS command. It also flushes the received buffer to prevent application from confusing received data before and after the setSecure call.

If the connection is already using TLS, nothing else happens.

connSetSecureWithCtx :: MonadIO m => ConnectionContext -> TLSSettings -> ConnectT m ()

Like connSetSecure, but uses the supplied ConnectionContext instead of using the same one which was used when opening the connection.

connIsSecure :: MonadIO m => ConnectT m Bool

Check whether the connection is established securely (using TLS).