Network.HTTP.Semantics.IO

http-semantics-0.3.0: HTTP senmatics libarry

Safe Haskell | None
Language | Haskell2010

Network.HTTP.Semantics.IO

Synopsis

- type ReadN = Int -> IO ByteString
- defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN
- type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount
- type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
- data Sentinel
  - = Closer (IO ())
  - | Refresher (IO ())
- defaultPositionReadMaker :: PositionReadMaker
- data Next
  - = Next BytesFilled Bool (Maybe DynaNext)
  - | CancelNext (Maybe SomeException)
- type DynaNext = Buffer -> Int -> IO Next
- type BytesFilled = Int
- data StreamingChunk
  - = StreamingFinished (Maybe CleanupStream)
  - | StreamingCancelled (Maybe SomeException)
  - | StreamingFlush
  - | StreamingBuilder Builder IsEndOfStream
- data IsEndOfStream
  - = NotEndOfStream
  - | EndOfStream (Maybe CleanupStream)
- type CleanupStream = IO ()
- fillBuilderBodyGetNext :: Builder -> DynaNext
- fillFileBodyGetNext :: PositionRead -> FileOffset -> ByteCount -> Sentinel -> DynaNext
- fillStreamBodyGetNext :: IO (Maybe StreamingChunk) -> DynaNext
- type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker
- data NextTrailersMaker
  - = NextTrailersMaker TrailersMaker
  - | Trailers [Header]
- defaultTrailersMaker :: TrailersMaker
- runTrailersMaker :: TrailersMaker -> Buffer -> Int -> IO NextTrailersMaker

# Documentation

type ReadN = Int -> IO ByteString #

Reading n bytes.

defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN #

Naive implementation for readN.

NOTE: This function is intended to be used by a single thread only. (It is probably quite rare anyway to want concurrent reads from the same network socket.)

type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount #

Position read for files.

type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel) #

Making a position read and its closer.

data Sentinel #

Constructors

Closer (IO ()) | Closing a file resource. Its refresher is automatiaclly generated by the internal timer.
Refresher (IO ()) | Refreshing a file resource while reading. Closing the file must be done by its own timer or something.

defaultPositionReadMaker :: PositionReadMaker #

Position read based on `Handle`.

data Next #

Constructors

Next BytesFilled Bool (Maybe DynaNext) |
CancelNext (Maybe SomeException) |

type DynaNext #

Arguments

= Buffer | Write buffer
-> Int | Maximum number of bytes we are allowed to write In `http2`, this maximum will be set to the space left in the write buffer. Implicitly this also means that this maximum cannot exceed the maximum size of a HTTP2 frame, since in `http2` the size of the write buffer is also used to set `SETTINGS_MAX_FRAME_SIZE` (see `confBufferSize`).
-> IO Next | Information on the data written, and on how to continue if not all data was written

Write part of a streaming response to the write buffer

In `http2` this will be used to construct a single HTTP2 `DATA` frame (see discussion of the maximum number of bytes, below).

type BytesFilled = Int #

data StreamingChunk #

Constructors

StreamingFinished (Maybe CleanupStream) | Indicate that the stream is finished
StreamingCancelled (Maybe SomeException) | Indicate that the stream is cancelled
StreamingFlush | Flush the stream This will cause the write buffer to be written to the network socket, without waiting for more data.
StreamingBuilder Builder IsEndOfStream | Construct a DATA frame, optionally terminating the stream

data IsEndOfStream #

Constructors

NotEndOfStream | The stream is not yet terminated
EndOfStream (Maybe CleanupStream) | The stream is terminated In addition to indicating that the stream is terminated, we can also specify an optional `Cleanup` handler to be run.

type CleanupStream = IO () #

Action to run prior to terminating the stream

fillBuilderBodyGetNext :: Builder -> DynaNext #

fillFileBodyGetNext :: PositionRead -> FileOffset -> ByteCount -> Sentinel -> DynaNext #

fillStreamBodyGetNext :: IO (Maybe StreamingChunk) -> DynaNext #

type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker #

Trailers maker. A chunks of the response body is passed with `Just`. The maker should update internal state with the `ByteString` and return the next trailers maker. When response body reaches its end, `Nothing` is passed and the maker should generate trailers. An example:

    {-# LANGUAGE BangPatterns #-}
    import Data.ByteString (ByteString)
    import qualified Data.ByteString.Char8 as C8
    import Crypto.Hash (Context, SHA1) -- cryptonite
    import qualified Crypto.Hash as CH

    -- Strictness is important for Context.
    trailersMaker :: Context SHA1 -> Maybe ByteString -> IO NextTrailersMaker
    trailersMaker ctx Nothing = return $ Trailers [("X-SHA1", sha1)]
      where
        !sha1 = C8.pack $ show $ CH.hashFinalize ctx
    trailersMaker ctx (Just bs) = return $ NextTrailersMaker $ trailersMaker ctx'
      where
        !ctx' = CH.hashUpdate ctx bs

Usage example:

    let h2rsp = responseFile ...
        maker = trailersMaker (CH.hashInit :: Context SHA1)
        h2rsp' = setResponseTrailersMaker h2rsp maker

data NextTrailersMaker #

Either the next trailers maker or final trailers.

Constructors

NextTrailersMaker TrailersMaker |
Trailers [Header] |

defaultTrailersMaker :: TrailersMaker #

TrailersMake to create no trailers.

runTrailersMaker :: TrailersMaker -> Buffer -> Int -> IO NextTrailersMaker #

Running trailers-maker.

    bufferIO buf siz $ \bs -> tlrmkr (Just bs)