SecondTransfer.Types

Documentation

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 Attendant = AttendantCallbacks -> IO ()

A function which takes three arguments: the first one says how to send data (on a socket or similar transport), and the second one how to receive data on the transport. The third argument encapsulates the sequence of steps needed for a clean shutdown.

You can implement one of these to let somebody else supply the push, pull and close callbacks. For example, tlsServeWithALPN will supply these arguments to an Attendant.

Attendants encapsulate all the session book-keeping functionality, which for HTTP/2 is quite complicated. You use the functions http**Attendant to create one of these from a CoherentWorker.

This library supplies two of such Attendant factories, http11Attendant for HTTP 1.1 sessions, and http2Attendant for HTTP/2 sessions.

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 AttendantCallbacks

Constructors

AttendantCallbacks

Fields

_pushAction_AtC :: PushAction

_pullAction_AtC :: PullAction

_bestEffortPullAction_AtC :: BestEffortPullAction

_closeAction_AtC :: CloseAction

pushAction_AtC :: Lens' AttendantCallbacks PushAction

pullAction_AtC :: Lens' AttendantCallbacks PullAction

closeAction_AtC :: Lens' AttendantCallbacks CloseAction

bestEffortPullAction_AtC :: Lens' AttendantCallbacks BestEffortPullAction

getHeaderFromFlatList :: Headers -> ByteString -> Maybe ByteString

Gets a single header from the list

nullFooter :: Source IO ByteString -> DataAndConclusion

If you want to skip the footers, i.e., they are empty, use this function to convert an ordinary Source to a DataAndConclusion.

type HeaderName = ByteString

The name part of a header

type HeaderValue = ByteString

The value part of a header

type Header = (HeaderName, HeaderValue)

The complete header

type Headers = [Header]

List of headers. The first part of each tuple is the header name (be sure to conform to the HTTP/2 convention of using lowercase) and the second part is the headers contents. This list needs to include the special :method, :scheme, :authority and :path pseudo-headers for requests; and :status (with a plain numeric value represented in ascii digits) for responses.

type FinalizationHeaders = Headers

Finalization headers. If you don't know what they are, chances are that you don't need to worry about them for now. The support in this library for those are at best sketchy.

data Request

A request is a set of headers and a request body.... which will normally be empty, except for POST and PUT requests. But this library enforces none of that.

Constructors

Request

Fields

_headers_RQ :: !Headers

_inputData_RQ :: Maybe InputDataStream

_perception_RQ :: !Perception

type Footers = FinalizationHeaders

Finalization headers

data Perception

Data related to the request

Constructors

Perception

Fields

_startedTime_Pr :: TimeSpec

_streamId_Pr :: Int

_sessionId_Pr :: Int

data Effect

Sometimes a response needs to be handled a bit specially, for example by reporting delivery details back to the worker

Constructors

Effect

Fields

_fragmentDeliveryCallback_Ef :: Maybe FragmentDeliveryCallback

_priorityEffect_Ef :: Maybe Int

type AwareWorker = Request -> IO PrincipalStream

Main type of this library. You implement one of these for your server. This is a callback that the library calls as soon as it has all the headers of a request. For GET requests that's the entire request basically, but for POST and PUT requests this is just before the data starts arriving to the server.

It is important that you consume the data in the cases where there is an input stream, otherwise the memory is lost for the duration of the request, and a malicious client can use that.

Also, notice that when handling requests your worker can be interrupted with an asynchronous exception of type StreamCancelledException, if the peer cancels the stream

data PrincipalStream

You use this type to answer a request. The Headers are thus response headers and they should contain the :status pseudo-header. The PushedStreams is a list of pushed streams...(I don't thaink that I'm handling those yet)

Constructors

PrincipalStream

Fields

_headers_PS :: Headers

_pushedStreams_PS :: PushedStreams

_dataAndConclusion_PS :: DataAndConclusion

_effect_PS :: Effect

type PushedStreams = [IO PushedStream]

A list of pushed streams. Notice that a list of IO computations is required here. These computations only happen when and if the streams are pushed to the client. The lazy nature of Haskell helps to avoid unneeded computations if the streams are not going to be sent to the client.

data PushedStream

A pushed stream, represented by a list of request headers, a list of response headers, and the usual response body (which may include final footers (not implemented yet)).

Constructors

PushedStream

Fields

_requestHeaders_Psh :: Headers

_responseHeaders_Psh :: Headers

_dataAndConclusion_Psh :: DataAndConclusion

type DataAndConclusion = ConduitM () ByteString IO Footers

A source-like conduit with the data returned in the response. The return value of the conduit is a list of footers. For now that list can be anything (even bottom), I'm not handling it just yet.

type CoherentWorker = (Headers, Maybe InputDataStream) -> IO (Headers, PushedStreams, DataAndConclusion)

A CoherentWorker is a less fuzzy worker, but less aware.

type InputDataStream = Source IO ByteString

This is a Source conduit (see Haskell Data.Conduit library from Michael Snoyman) that you can use to retrieve the data sent by the client piece-wise.

type TupledPrincipalStream = (Headers, PushedStreams, DataAndConclusion)

Not exactly equivalent of the prinicipal stream

type FragmentDeliveryCallback = Int -> TimeSpec -> IO ()

First argument is the ordinal of this data frame, second an approximation of when the frame was delivered, according to the monotonic clock. Do not linger in this call, it may delay some important thread

headers_RQ :: Lens' Request Headers

inputData_RQ :: Lens' Request (Maybe InputDataStream)

perception_RQ :: Lens' Request Perception

headers_PS :: Lens' PrincipalStream Headers

pushedStreams_PS :: Lens' PrincipalStream PushedStreams

dataAndConclusion_PS :: Lens' PrincipalStream DataAndConclusion

dataAndConclusion_Psh :: Lens' PushedStream DataAndConclusion

requestHeaders_Psh :: Lens' PushedStream Headers

responseHeaders_Psh :: Lens' PushedStream Headers

effect_PS :: Lens' PrincipalStream Effect

startedTime_Pr :: Lens' Perception TimeSpec

streamId_Pr :: Lens' Perception Int

sessionId_Pr :: Lens' Perception Int

fragmentDeliveryCallback_Ef :: Lens' Effect (Maybe FragmentDeliveryCallback)

priorityEffect_Ef :: Lens' Effect (Maybe Int)

defaultEffects :: Effect

coherentToAwareWorker :: CoherentWorker -> AwareWorker

tupledPrincipalStreamToPrincipalStream :: TupledPrincipalStream -> PrincipalStream

requestToTupledRequest :: Request -> TupledRequest