Safe Haskell	None
Language	Haskell2010

SecondTransfer.Types

Synopsis

Documentation

type PushAction = ByteString -> IO () Source

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 Source

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 Source

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 = IOCallbacks -> IO () Source

This is an intermediate type. It represents what you obtain by combining something that speaks the protocol and an AwareWorker. In turn, you need to feed a bundle of callbacks implementing I/O to finally start a server.

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

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 Source

A set of functions describing how to do I/O in a session. As usual, we provide lenses accessors.

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.
_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.
_closeAction_IOC :: CloseAction: this is called when we wish to close the channel.

pushAction_IOC :: Lens' IOCallbacks PushAction Source

pullAction_IOC :: Lens' IOCallbacks PullAction Source

closeAction_IOC :: Lens' IOCallbacks CloseAction Source

bestEffortPullAction_IOC :: Lens' IOCallbacks BestEffortPullAction Source

getHeaderFromFlatList :: Headers -> ByteString -> Maybe ByteString Source

Gets a single header from the list

nullFooter :: Source IO ByteString -> DataAndConclusion Source

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 Source

The name part of a header

type HeaderValue = ByteString Source

The value part of a header

type Header = (HeaderName, HeaderValue) Source

The complete header

type Headers = [Header] Source

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 Source

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 Source

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 Source

Finalization headers

data Perception Source

Data related to the request

Constructors

Perception

Fields

_streamId_Pr :: Int: The HTTP/2 stream id. Or the serial number of the request in an HTTP/1.1 session.
_sessionId_Pr :: Int: A number uniquely identifying the session. This number is unique and the same for each TPC connection that a client opens using a given protocol.
_startedTime_Pr :: TimeSpec: Monotonic time close to when the request was first seen in the processing pipeline.
_protocol_Pr :: HttpProtocolVersion: Which protocol is serving the request
_anouncedProtocols_Pr :: Maybe [ByteString]: For new connections, probably a list of anounced protocols

data Effect Source

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: A callback to be called whenever a data-packet for this stream is called.
_priorityEffect_Ef :: Maybe Int: In certain circunstances a stream can use an internal priority, not given by the browser and the protocol. Lowest values here are given more priority. Default (when Nothing) is given zero. Cases with negative numbers also work.
_interrupt_Ef :: Maybe InterruptEffect: There are situations when it is desirable to close a stream or the entire connection. Use this member to indicate that.

type AwareWorker = Request -> IO PrincipalStream Source

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 Source

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... they will be pushed to the client.

Constructors

PrincipalStream
Fields _headers_PS :: Headers _pushedStreams_PS :: PushedStreams _dataAndConclusion_PS :: DataAndConclusion _effect_PS :: Effect

type PushedStreams = [IO PushedStream] Source

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 Source

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 Source

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 = TupledRequest -> IO TupledPrincipalStream Source

A CoherentWorker is a simplified callback that you can implement to handle requests. Then you can convert it to an AwareWorker with tupledPrincipalStreamToPrincipalStream.

type InputDataStream = Source IO ByteString Source

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

type TupledPrincipalStream = (Headers, PushedStreams, DataAndConclusion) Source

A tuple representing the data alone that you usually need to give as a response, that is, the headers in the response (including the HTTP/2 :status), any pushed streams, a stream with the response data and the footers.

type TupledRequest = (Headers, Maybe InputDataStream) Source

A tuple representing the data alone usually needed to create a response. That is, the headers (including HTTP/2 :path, :authority, etc) and maybe an input data stream for requests that include it, that is, POST and PUT.

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

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

data InterruptEffect Source

Types of interrupt effects that can be signaled by aware workers. These include whole connection shutdowns and stream resets. In all the cases, the reason given will be NO_ERROR.

Constructors

InterruptConnectionAfter_IEf	Close and send GoAway after this stream finishes delivery
InterruptConnectionNow_IEf	Close and send GoAway without delivering this stream. This implies that other fields of the PrincipalStream record will be ignored. \|InterruptThisStream_IEf -- ^ Just reset this stream, disabled for now.

headers_RQ :: Lens' Request Headers Source

inputData_RQ :: Lens' Request (Maybe InputDataStream) Source

perception_RQ :: Lens' Request Perception Source

headers_PS :: Lens' PrincipalStream Headers Source

pushedStreams_PS :: Lens' PrincipalStream PushedStreams Source

dataAndConclusion_PS :: Lens' PrincipalStream DataAndConclusion Source

dataAndConclusion_Psh :: Lens' PushedStream DataAndConclusion Source

requestHeaders_Psh :: Lens' PushedStream Headers Source

responseHeaders_Psh :: Lens' PushedStream Headers Source

effect_PS :: Lens' PrincipalStream Effect Source

startedTime_Pr :: Lens' Perception TimeSpec Source

streamId_Pr :: Lens' Perception Int Source