SecondTransfer.IOCallbacks.Types

Documentation

Functions for passing data to external parties The callbacks here should have a blocking behavior and not return empty results unless at end of file.

Fundamental types and accessors

type PushAction = ByteString -> IO ()

Callback type to push data to a channel. Part of this interface is the abstract exception type IOProblem. Throw an instance of it from here to notify the session that the connection has been broken. There is no way to signal "normal termination", since HTTP/2's normal termination can be observed at a higher level when a GO_AWAY frame is seen.

type PullAction = Int -> IO ByteString

Callback type to pull data from a channel. The same as to PushAction applies to exceptions thrown from there. The first argument is the number of bytes to pull from the medium. Barring exceptions, we always know how many bytes we are expecting with HTTP/2.

type BestEffortPullAction = Bool -> IO ByteString

Callback type to pull data from a channel in a best-effort basis. When the first argument is True, the data-providing backend can block if the input buffers are empty and await for new data. Otherwise, it will return immediately with an empty ByteString

type Attendant = ConnectionData -> IOCallbacks -> IO ()

An Attendant is an entity that can speak a protocol, given the presented I/O callbacks. It's work is to spawn a set of threads to handle a client's session, and then return to the caller. It shouldn'r busy the calling thread.

type CloseAction = IO ()

Callback that the session calls to realease resources associated with the channels. Take into account that your callback should be able to deal with non-clean shutdowns also, for example, if the connection to the remote peer is severed suddenly.

data IOCallbacks

A set of functions describing how to do I/O in a session. There is one rule for IOCallbacks: only one user of it. That is, only one can write, only one can read concurrently. We don't protect for anything else, so concurrent read and writes would result in terrible things happening.

Constructors

IOCallbacks

Fields

_pushAction_IOC :: PushAction

put some data in the channel

_pullAction_IOC :: PullAction

get exactly this much data from the channel. This function can be used by HTTP/2 since lengths are pretty well built inside the protocoll itself. An exception of type NoMoreDataException can be raised from here inside if the channel is closed. This is done to notify the caller that there is no more data. The alternative would be to return an empty string, but that looks more hazardous for the caller.

_bestEffortPullAction_IOC :: BestEffortPullAction

pull data from the channel, as much as the TCP stack wants to provide. we have no option but use this one when talking HTTP/1.1, where the best way to know the length is to scan until a Content-Length is found. This will also raise NoMoreDataException when there is no more data. Notice that with argument False, this may return an empty string.

_closeAction_IOC :: CloseAction

this is called when we wish to close the channel.

pushAction_IOC :: Lens' IOCallbacks PushAction

pullAction_IOC :: Lens' IOCallbacks PullAction

closeAction_IOC :: Lens' IOCallbacks CloseAction

bestEffortPullAction_IOC :: Lens' IOCallbacks BestEffortPullAction

Classifying IO callbacks

class IOChannels a where

An object a which is IOChannels

Methods

handshake :: a -> IO IOCallbacks

This method should only be invoked once for the a instance. It will block/wait for any handshakes to complete, and only then return a usable set of callbacks.

Instances

IOChannels SaveReadFragment

IOChannels SocketIOCallbacks

IOChannels TLSServerSocketIOCallbacks

IOChannels IOCSideB

IOChannels IOCSideA

class IOChannels a => PlainTextIO a

Data exchanged through this channel is plain text

class IOChannels a => TLSEncryptedIO a

Data exchanged through this channel is the data of a TLS session

Instances

TLSEncryptedIO TLSServerSocketIOCallbacks

class TLSEncryptedIO a => TLSServerIO a

The agent putting and retrieving data in this side of the channel should behave as a TLS server

Instances

TLSServerIO TLSServerSocketIOCallbacks

class TLSEncryptedIO a => TLSClientIO a

The agent putting and retrieving data in this side of the channel should behave as a TLS client

class IOChannels a => SOCKS5Preface a

Data exchanged through this channel begins with a SOCKS5 negotiation

newtype ConnectionData

Some context related to a connection

Constructors

ConnectionData

Fields

_addr_CnD :: Maybe HashableSockAddr

addr_CnD :: Iso' ConnectionData (Maybe HashableSockAddr)

nullConnectionData :: ConnectionData

Utility functions

data PullActionWrapping

Generic implementation of PullAction from BestEffortPullAction, where we keep around any leftovers data ...

newPullActionWrapping :: BestEffortPullAction -> IO PullActionWrapping

pullFromWrapping' :: PullActionWrapping -> Int -> IO ByteString

The type of this function is also PullActionWrapping -> PullAction There should be only one reader concurrently.

bestEffortPullFromWrapping :: PullActionWrapping -> Bool -> IO ByteString