-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Version-independent common parts of HTTP
@package http-semantics
@version 0.3.0

module Network.HTTP.Semantics.Server.Internal

-- | Request from client.
newtype Request
Request :: InpObj -> Request

-- | Response from server.
newtype Response
Response :: OutObj -> Response

-- | Additional information.
data Aux
Aux :: Handle -> SockAddr -> SockAddr -> Aux

-- | Time handle for the worker processing this request and response.
[auxTimeHandle] :: Aux -> Handle

-- | Local socket address copied from <tt>Config</tt>.
[auxMySockAddr] :: Aux -> SockAddr

-- | Remove socket address copied from <tt>Config</tt>.
[auxPeerSockAddr] :: Aux -> SockAddr
instance GHC.Internal.Show.Show Network.HTTP.Semantics.Server.Internal.Request
instance GHC.Internal.Show.Show Network.HTTP.Semantics.Server.Internal.Response

module Network.HTTP.Semantics.Client.Internal

-- | Request from client.
newtype Request
Request :: OutObj -> Request

-- | Response from server.
newtype Response
Response :: InpObj -> Response

-- | Additional information.
data Aux
Aux :: IO Int -> Aux

-- | How many streams can be created without blocking.
[auxPossibleClientStreams] :: Aux -> IO Int
instance GHC.Internal.Show.Show Network.HTTP.Semantics.Client.Internal.Request
instance GHC.Internal.Show.Show Network.HTTP.Semantics.Client.Internal.Response


-- | Library for HTTP Semantics (<a>RFC9110</a>), version-independent
--   common parts. For low-level headers, <a>Token</a> is used. For
--   upper-level headers, <a>HeaderName</a> should be used.
module Network.HTTP.Semantics

-- | TrailersMake to create no trailers.
defaultTrailersMaker :: TrailersMaker

-- | Either the next trailers maker or final trailers.
data NextTrailersMaker
NextTrailersMaker :: TrailersMaker -> NextTrailersMaker
Trailers :: [Header] -> NextTrailersMaker

-- | Trailers maker. A chunks of the response body is passed with
--   <a>Just</a>. The maker should update internal state with the
--   <a>ByteString</a> and return the next trailers maker. When response
--   body reaches its end, <a>Nothing</a> is passed and the maker should
--   generate trailers. An example:
--   
--   <pre>
--   {-# 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 -&gt; Maybe ByteString -&gt; 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
--   </pre>
--   
--   Usage example:
--   
--   <pre>
--   let h2rsp = responseFile ...
--       maker = trailersMaker (CH.hashInit :: Context SHA1)
--       h2rsp' = setResponseTrailersMaker h2rsp maker
--   </pre>
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker

-- | Authority.
type Authority = String

-- | How many bytes to read
type ByteCount = Int64

-- | Offset for file.
type FileOffset = Int64

-- | File specification.
data FileSpec
FileSpec :: FilePath -> FileOffset -> ByteCount -> FileSpec
type InpBody = IO (ByteString, Bool)

-- | Input object
data InpObj
InpObj :: TokenHeaderTable -> Maybe Int -> InpBody -> IORef (Maybe TokenHeaderTable) -> InpObj

-- | Accessor for headers.
[inpObjHeaders] :: InpObj -> TokenHeaderTable

-- | Accessor for body length specified in content-length:.
[inpObjBodySize] :: InpObj -> Maybe Int

-- | Accessor for body.
[inpObjBody] :: InpObj -> InpBody

-- | Accessor for trailers.
[inpObjTrailers] :: InpObj -> IORef (Maybe TokenHeaderTable)
data OutBody
OutBodyNone :: OutBody

-- | Streaming body takes a write action and a flush action.
OutBodyStreaming :: ((Builder -> IO ()) -> IO () -> IO ()) -> OutBody

-- | Generalization of <a>OutBodyStreaming</a>.
OutBodyStreamingIface :: (OutBodyIface -> IO ()) -> OutBody
OutBodyBuilder :: Builder -> OutBody
OutBodyFile :: FileSpec -> OutBody
data OutBodyIface
OutBodyIface :: (forall x. () => IO x -> IO x) -> (Builder -> IO ()) -> (Builder -> IO ()) -> (Maybe SomeException -> IO ()) -> IO () -> OutBodyIface

-- | Unmask exceptions in the thread spawned for the request body
--   
--   This is used in the client: we spawn the new thread for the request
--   body with exceptions masked, and provide the body of
--   <a>OutBodyStreamingIface</a> with a callback to unmask them again
--   (typically after installing an exception handler).
--   
--   Unmasking in the server is a no-op, as here the scope of the thread
--   that is spawned for the server is the entire handler, not just the
--   response streaming body.
[outBodyUnmask] :: OutBodyIface -> forall x. () => IO x -> IO x

-- | Push a new chunk
--   
--   In <tt>http2</tt>, there is no direct correspondence between chunks
--   and the resulting <tt>DATA</tt> frames sent: the chunks are collected
--   (written to an internal write buffer) until we can fill a frame.
--   
--   See also <a>outBodyFlush</a>.
[outBodyPush] :: OutBodyIface -> Builder -> IO ()

-- | Push the final chunk
--   
--   Using this function instead of <a>outBodyPush</a> can be used to
--   guarantee that the final HTTP2 DATA frame is marked end-of-stream;
--   with <a>outBodyPush</a> it may happen that an additional empty DATA
--   frame is used for this purpose. Additionally, after calling this
--   function, <a>outBodyCancel</a> will be a no-op.
[outBodyPushFinal] :: OutBodyIface -> Builder -> IO ()

-- | Cancel the stream
--   
--   Sends a <tt>RST_STREAM</tt> to the peer. If cancelling as the result
--   of an exception, a <a>Just</a> should be provided which specifies the
--   exception which will be stored locally as the reason for cancelling
--   the stream; in this case, the error code sent with the
--   <tt>RST_STREAM</tt> will be <tt>INTERNAL_ERROR</tt> (see
--   <a>https://datatracker.ietf.org/doc/html/rfc7540#section-7</a>). If
--   <a>Nothing</a> is given, the error code will be <tt>CANCEL</tt>.
--   
--   If there is a partially constructed <tt>DATA</tt> frame at the time of
--   cancellation, this frame is discarded. If this is undesirable, you
--   should call <a>outBodyFlush</a> prior to cancelling.
[outBodyCancel] :: OutBodyIface -> Maybe SomeException -> IO ()

-- | Flush
--   
--   This can be used to emit a DATA frame with the data collected so far
--   (using <a>outBodyPush</a>), even if that DATA frame has not yet
--   reached the maximum frame size. Calling <a>outBodyFlush</a>
--   unnecessarily can therefore result in excessive overhead from frame
--   headers.
--   
--   If no data is available to send, this is a no-op.
[outBodyFlush] :: OutBodyIface -> IO ()

-- | Output object
data OutObj
OutObj :: [Header] -> OutBody -> TrailersMaker -> OutObj

-- | Accessor for header.
[outObjHeaders] :: OutObj -> [Header]

-- | Accessor for outObj body.
[outObjBody] :: OutObj -> OutBody

-- | Accessor for trailers maker.
[outObjTrailers] :: OutObj -> TrailersMaker

-- | Path.
type Path = ByteString

-- | "http" or "https".
type Scheme = ByteString

-- | Accessing <a>FieldValue</a> with <a>Token</a>.
getFieldValue :: Token -> ValueTable -> Maybe FieldValue

-- | Accessing <a>FieldValue</a> with <a>Token</a>.

-- | <i>Deprecated: use geFieldValue instead</i>
getHeaderValue :: Token -> ValueTable -> Maybe FieldValue

-- | Field name. Internal usage only.
type FieldName = ByteString

-- | Field value.
type FieldValue = ByteString

-- | A pair of token list and value table.

-- | <i>Deprecated: use TokenHeaderTable instead</i>
type HeaderTable = (TokenHeaderList, ValueTable)

-- | Header value.

-- | <i>Deprecated: use FieldValue instead</i>
type HeaderValue = ByteString

-- | TokenBased header.
type TokenHeader = (Token, FieldValue)

-- | TokenBased header list.
type TokenHeaderList = [TokenHeader]

-- | A pair of token list and value table.
type TokenHeaderTable = (TokenHeaderList, ValueTable)

-- | An array to get <a>FieldValue</a> quickly. <a>getHeaderValue</a>
--   should be used. Internally, the key is <a>tokenIx</a>.
type ValueTable = Array Int Maybe FieldValue

-- | Token index for <a>tokenCookie</a>.
cookieTokenIx :: Int

-- | Is this token ix for Cookie?
isCookieTokenIx :: Int -> Bool

-- | Is this token ix to be held in the place holder?
isMaxTokenIx :: Int -> Bool

-- | Is this token for a header not defined in the static table?
isStaticToken :: Token -> Bool

-- | Is this token ix for a header not defined in the static table?
isStaticTokenIx :: Int -> Bool

-- | Maximun token index defined in the static table.
maxStaticTokenIx :: Int

-- | Maximum token index.
maxTokenIx :: Int

-- | Minimum token index.
minTokenIx :: Int

-- | Making a token from a header key.
--   
--   <pre>
--   &gt;&gt;&gt; toToken ":authority" == tokenAuthority
--   True
--   
--   &gt;&gt;&gt; toToken "foo"
--   Token {tokenIx = 73, shouldBeIndexed = True, isPseudo = False, tokenKey = "foo"}
--   
--   &gt;&gt;&gt; toToken ":bar"
--   Token {tokenIx = 73, shouldBeIndexed = True, isPseudo = True, tokenKey = ":bar"}
--   </pre>
toToken :: ByteString -> Token
tokenAccept :: Token
tokenAcceptCharset :: Token
tokenAcceptEncoding :: Token
tokenAcceptLanguage :: Token
tokenAcceptRanges :: Token

-- | For QPACK
tokenAccessControlAllowCredentials :: Token
tokenAccessControlAllowHeaders :: Token
tokenAccessControlAllowMethods :: Token
tokenAccessControlAllowOrigin :: Token
tokenAccessControlExposeHeaders :: Token
tokenAccessControlRequestHeaders :: Token
tokenAccessControlRequestMethod :: Token
tokenAge :: Token
tokenAllow :: Token
tokenAltSvc :: Token
tokenAuthority :: Token
tokenAuthorization :: Token

-- | Extracting a case insensitive header key from a token.
tokenCIKey :: Token -> ByteString
tokenCacheControl :: Token

-- | A place holder to hold header keys not defined in the static table. |
--   For Warp
tokenConnection :: Token
tokenContentDisposition :: Token
tokenContentEncoding :: Token
tokenContentLanguage :: Token
tokenContentLength :: Token
tokenContentLocation :: Token
tokenContentRange :: Token
tokenContentSecurityPolicy :: Token
tokenContentType :: Token
tokenCookie :: Token
tokenDate :: Token
tokenEarlyData :: Token
tokenEtag :: Token
tokenExpect :: Token
tokenExpectCt :: Token
tokenExpires :: Token

-- | Extracting a folded header key from a token.
tokenFoldedKey :: Token -> ByteString
tokenForwarded :: Token
tokenFrom :: Token
tokenHost :: Token
tokenIfMatch :: Token
tokenIfModifiedSince :: Token
tokenIfNoneMatch :: Token
tokenIfRange :: Token
tokenIfUnmodifiedSince :: Token
tokenLastModified :: Token
tokenLink :: Token
tokenLocation :: Token
tokenMax :: Token
tokenMaxForwards :: Token
tokenMethod :: Token
tokenOrigin :: Token
tokenPath :: Token
tokenProxyAuthenticate :: Token
tokenProxyAuthorization :: Token
tokenPurpose :: Token
tokenRange :: Token
tokenReferer :: Token
tokenRefresh :: Token
tokenRetryAfter :: Token
tokenScheme :: Token
tokenServer :: Token
tokenSetCookie :: Token
tokenStatus :: Token
tokenStrictTransportSecurity :: Token
tokenTE :: Token
tokenTimingAllowOrigin :: Token
tokenTransferEncoding :: Token
tokenUpgradeInsecureRequests :: Token
tokenUserAgent :: Token
tokenVary :: Token
tokenVia :: Token
tokenWwwAuthenticate :: Token
tokenXContentTypeOptions :: Token
tokenXForwardedFor :: Token
tokenXFrameOptions :: Token
tokenXXssProtection :: Token

-- | Internal representation for header keys.
data Token
Token :: Int -> Bool -> Bool -> HeaderName -> Token

-- | Index for value table
[tokenIx] :: Token -> Int

-- | should be indexed in HPACK
[shouldBeIndexed] :: Token -> Bool

-- | is this a pseudo header key?
[isPseudo] :: Token -> Bool

-- | Case insensitive header key
[tokenKey] :: Token -> HeaderName

module Network.HTTP.Semantics.Server

-- | Server type. Server takes a HTTP request, should generate a HTTP
--   response and push promises, then should give them to the sending
--   function. The sending function would throw exceptions so that they can
--   be logged.
--   
--   The sending function must only be called once.
type Server = Request -> Aux -> Response -> [PushPromise] -> IO () -> IO ()

-- | Request from client.
data Request

-- | Getting the method from a request.
requestMethod :: Request -> Maybe Method

-- | Getting the path from a request.
requestPath :: Request -> Maybe Path

-- | Getting the authority from a request.
requestAuthority :: Request -> Maybe Authority

-- | Getting the scheme from a request.
requestScheme :: Request -> Maybe Scheme

-- | Getting the headers from a request.
requestHeaders :: Request -> TokenHeaderTable

-- | Getting the body size from a request.
requestBodySize :: Request -> Maybe Int

-- | Reading a chunk of the request body. An empty <a>ByteString</a>
--   returned when finished.
getRequestBodyChunk :: Request -> IO ByteString

-- | Generalization of <a>getRequestBodyChunk</a> which also returns if the
--   <a>ByteString</a> is the final one
getRequestBodyChunk' :: Request -> IO (ByteString, Bool)

-- | Reading request trailers. This function must be called after
--   <a>getRequestBodyChunk</a> returns an empty.
getRequestTrailers :: Request -> IO (Maybe TokenHeaderTable)

-- | Additional information.
data Aux

-- | Time handle for the worker processing this request and response.
auxTimeHandle :: Aux -> Handle

-- | Local socket address copied from <tt>Config</tt>.
auxMySockAddr :: Aux -> SockAddr

-- | Remove socket address copied from <tt>Config</tt>.
auxPeerSockAddr :: Aux -> SockAddr

-- | Response from server.
data Response

-- | Creating response without body.
responseNoBody :: Status -> ResponseHeaders -> Response

-- | Creating response with file.
responseFile :: Status -> ResponseHeaders -> FileSpec -> Response

-- | Creating response with streaming.
responseStreaming :: Status -> ResponseHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Response

-- | Creating response with builder.
responseBuilder :: Status -> ResponseHeaders -> Builder -> Response
data OutBodyIface
OutBodyIface :: (forall x. () => IO x -> IO x) -> (Builder -> IO ()) -> (Builder -> IO ()) -> (Maybe SomeException -> IO ()) -> IO () -> OutBodyIface

-- | Unmask exceptions in the thread spawned for the request body
--   
--   This is used in the client: we spawn the new thread for the request
--   body with exceptions masked, and provide the body of
--   <a>OutBodyStreamingIface</a> with a callback to unmask them again
--   (typically after installing an exception handler).
--   
--   Unmasking in the server is a no-op, as here the scope of the thread
--   that is spawned for the server is the entire handler, not just the
--   response streaming body.
[outBodyUnmask] :: OutBodyIface -> forall x. () => IO x -> IO x

-- | Push a new chunk
--   
--   In <tt>http2</tt>, there is no direct correspondence between chunks
--   and the resulting <tt>DATA</tt> frames sent: the chunks are collected
--   (written to an internal write buffer) until we can fill a frame.
--   
--   See also <a>outBodyFlush</a>.
[outBodyPush] :: OutBodyIface -> Builder -> IO ()

-- | Push the final chunk
--   
--   Using this function instead of <a>outBodyPush</a> can be used to
--   guarantee that the final HTTP2 DATA frame is marked end-of-stream;
--   with <a>outBodyPush</a> it may happen that an additional empty DATA
--   frame is used for this purpose. Additionally, after calling this
--   function, <a>outBodyCancel</a> will be a no-op.
[outBodyPushFinal] :: OutBodyIface -> Builder -> IO ()

-- | Cancel the stream
--   
--   Sends a <tt>RST_STREAM</tt> to the peer. If cancelling as the result
--   of an exception, a <a>Just</a> should be provided which specifies the
--   exception which will be stored locally as the reason for cancelling
--   the stream; in this case, the error code sent with the
--   <tt>RST_STREAM</tt> will be <tt>INTERNAL_ERROR</tt> (see
--   <a>https://datatracker.ietf.org/doc/html/rfc7540#section-7</a>). If
--   <a>Nothing</a> is given, the error code will be <tt>CANCEL</tt>.
--   
--   If there is a partially constructed <tt>DATA</tt> frame at the time of
--   cancellation, this frame is discarded. If this is undesirable, you
--   should call <a>outBodyFlush</a> prior to cancelling.
[outBodyCancel] :: OutBodyIface -> Maybe SomeException -> IO ()

-- | Flush
--   
--   This can be used to emit a DATA frame with the data collected so far
--   (using <a>outBodyPush</a>), even if that DATA frame has not yet
--   reached the maximum frame size. Calling <a>outBodyFlush</a>
--   unnecessarily can therefore result in excessive overhead from frame
--   headers.
--   
--   If no data is available to send, this is a no-op.
[outBodyFlush] :: OutBodyIface -> IO ()

-- | Generalization of <a>responseStreaming</a>.
responseStreamingIface :: Status -> ResponseHeaders -> (OutBodyIface -> IO ()) -> Response

-- | Getter for response body size. This value is available for file body.
responseBodySize :: Response -> Maybe Int

-- | Trailers maker. A chunks of the response body is passed with
--   <a>Just</a>. The maker should update internal state with the
--   <a>ByteString</a> and return the next trailers maker. When response
--   body reaches its end, <a>Nothing</a> is passed and the maker should
--   generate trailers. An example:
--   
--   <pre>
--   {-# 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 -&gt; Maybe ByteString -&gt; 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
--   </pre>
--   
--   Usage example:
--   
--   <pre>
--   let h2rsp = responseFile ...
--       maker = trailersMaker (CH.hashInit :: Context SHA1)
--       h2rsp' = setResponseTrailersMaker h2rsp maker
--   </pre>
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker

-- | Either the next trailers maker or final trailers.
data NextTrailersMaker
NextTrailersMaker :: TrailersMaker -> NextTrailersMaker
Trailers :: [Header] -> NextTrailersMaker

-- | TrailersMake to create no trailers.
defaultTrailersMaker :: TrailersMaker

-- | Setting <a>TrailersMaker</a> to <a>Response</a>.
setResponseTrailersMaker :: Response -> TrailersMaker -> Response

-- | HTTP/2 push promise or sever push. Pseudo REQUEST headers in push
--   promise is automatically generated. Then, a server push is sent
--   according to <a>promiseResponse</a>.
data PushPromise
PushPromise :: ByteString -> Response -> PushPromise

-- | Accessor for a URL path in a push promise (a virtual request from a
--   server). E.g. "/style/default.css".
[promiseRequestPath] :: PushPromise -> ByteString

-- | Accessor for response actually pushed from a server.
[promiseResponse] :: PushPromise -> Response

-- | Creating push promise. The third argument is traditional, not used.
pushPromise :: ByteString -> Response -> Int -> PushPromise

-- | Path.
type Path = ByteString

-- | Authority.
type Authority = String

-- | "http" or "https".
type Scheme = ByteString

-- | File specification.
data FileSpec
FileSpec :: FilePath -> FileOffset -> ByteCount -> FileSpec

-- | Offset for file.
type FileOffset = Int64

-- | How many bytes to read
type ByteCount = Int64

-- | Naive implementation for readN.
--   
--   <i>NOTE</i>: This function is intended to be used by a single thread
--   only. (It is probably quite rare anyway to want concurrent reads from
--   the <i>same</i> network socket.)
defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN

-- | Reading n bytes.
type ReadN = Int -> IO ByteString

-- | Position read based on <a>Handle</a>.
defaultPositionReadMaker :: PositionReadMaker

-- | Position read for files.
type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount

-- | Making a position read and its closer.
type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
data Sentinel

-- | Closing a file resource. Its refresher is automatiaclly generated by
--   the internal timer.
Closer :: IO () -> Sentinel

-- | Refreshing a file resource while reading. Closing the file must be
--   done by its own timer or something.
Refresher :: IO () -> Sentinel

module Network.HTTP.Semantics.Client

-- | Client type.
type Client a = SendRequest -> Aux -> IO a

-- | Send a request and receive its response.
type SendRequest = forall r. () => Request -> Response -> IO r -> IO r

-- | Request from client.
data Request

-- | Creating request without body.
requestNoBody :: Method -> Path -> RequestHeaders -> Request

-- | Creating request with file.
requestFile :: Method -> Path -> RequestHeaders -> FileSpec -> Request

-- | Creating request with streaming.
requestStreaming :: Method -> Path -> RequestHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Request

-- | Like <a>requestStreaming</a>, but run the action with exceptions
--   masked
requestStreamingUnmask :: Method -> Path -> RequestHeaders -> ((forall x. () => IO x -> IO x) -> (Builder -> IO ()) -> IO () -> IO ()) -> Request

-- | Creating request with builder.
requestBuilder :: Method -> Path -> RequestHeaders -> Builder -> Request
data OutBodyIface
OutBodyIface :: (forall x. () => IO x -> IO x) -> (Builder -> IO ()) -> (Builder -> IO ()) -> (Maybe SomeException -> IO ()) -> IO () -> OutBodyIface

-- | Unmask exceptions in the thread spawned for the request body
--   
--   This is used in the client: we spawn the new thread for the request
--   body with exceptions masked, and provide the body of
--   <a>OutBodyStreamingIface</a> with a callback to unmask them again
--   (typically after installing an exception handler).
--   
--   Unmasking in the server is a no-op, as here the scope of the thread
--   that is spawned for the server is the entire handler, not just the
--   response streaming body.
[outBodyUnmask] :: OutBodyIface -> forall x. () => IO x -> IO x

-- | Push a new chunk
--   
--   In <tt>http2</tt>, there is no direct correspondence between chunks
--   and the resulting <tt>DATA</tt> frames sent: the chunks are collected
--   (written to an internal write buffer) until we can fill a frame.
--   
--   See also <a>outBodyFlush</a>.
[outBodyPush] :: OutBodyIface -> Builder -> IO ()

-- | Push the final chunk
--   
--   Using this function instead of <a>outBodyPush</a> can be used to
--   guarantee that the final HTTP2 DATA frame is marked end-of-stream;
--   with <a>outBodyPush</a> it may happen that an additional empty DATA
--   frame is used for this purpose. Additionally, after calling this
--   function, <a>outBodyCancel</a> will be a no-op.
[outBodyPushFinal] :: OutBodyIface -> Builder -> IO ()

-- | Cancel the stream
--   
--   Sends a <tt>RST_STREAM</tt> to the peer. If cancelling as the result
--   of an exception, a <a>Just</a> should be provided which specifies the
--   exception which will be stored locally as the reason for cancelling
--   the stream; in this case, the error code sent with the
--   <tt>RST_STREAM</tt> will be <tt>INTERNAL_ERROR</tt> (see
--   <a>https://datatracker.ietf.org/doc/html/rfc7540#section-7</a>). If
--   <a>Nothing</a> is given, the error code will be <tt>CANCEL</tt>.
--   
--   If there is a partially constructed <tt>DATA</tt> frame at the time of
--   cancellation, this frame is discarded. If this is undesirable, you
--   should call <a>outBodyFlush</a> prior to cancelling.
[outBodyCancel] :: OutBodyIface -> Maybe SomeException -> IO ()

-- | Flush
--   
--   This can be used to emit a DATA frame with the data collected so far
--   (using <a>outBodyPush</a>), even if that DATA frame has not yet
--   reached the maximum frame size. Calling <a>outBodyFlush</a>
--   unnecessarily can therefore result in excessive overhead from frame
--   headers.
--   
--   If no data is available to send, this is a no-op.
[outBodyFlush] :: OutBodyIface -> IO ()

-- | Generalized version of <a>requestStreaming</a>,
requestStreamingIface :: Method -> Path -> RequestHeaders -> (OutBodyIface -> IO ()) -> Request

-- | Trailers maker. A chunks of the response body is passed with
--   <a>Just</a>. The maker should update internal state with the
--   <a>ByteString</a> and return the next trailers maker. When response
--   body reaches its end, <a>Nothing</a> is passed and the maker should
--   generate trailers. An example:
--   
--   <pre>
--   {-# 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 -&gt; Maybe ByteString -&gt; 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
--   </pre>
--   
--   Usage example:
--   
--   <pre>
--   let h2rsp = responseFile ...
--       maker = trailersMaker (CH.hashInit :: Context SHA1)
--       h2rsp' = setResponseTrailersMaker h2rsp maker
--   </pre>
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker

-- | Either the next trailers maker or final trailers.
data NextTrailersMaker
NextTrailersMaker :: TrailersMaker -> NextTrailersMaker
Trailers :: [Header] -> NextTrailersMaker

-- | TrailersMake to create no trailers.
defaultTrailersMaker :: TrailersMaker

-- | Setting <a>TrailersMaker</a> to <a>Response</a>.
setRequestTrailersMaker :: Request -> TrailersMaker -> Request

-- | Response from server.
data Response

-- | Getting the status of a response.
responseStatus :: Response -> Maybe Status

-- | Getting the headers from a response.
responseHeaders :: Response -> TokenHeaderTable

-- | Getting the body size from a response.
responseBodySize :: Response -> Maybe Int

-- | Reading a chunk of the response body. An empty <a>ByteString</a>
--   returned when finished.
getResponseBodyChunk :: Response -> IO ByteString

-- | Generalization of <a>getResponseBodyChunk</a> which also returns if
--   the <a>ByteString</a> is the final one
getResponseBodyChunk' :: Response -> IO (ByteString, Bool)

-- | Reading response trailers. This function must be called after
--   <a>getResponseBodyChunk</a> returns an empty.
getResponseTrailers :: Response -> IO (Maybe TokenHeaderTable)

-- | Additional information.
data Aux

-- | How many streams can be created without blocking.
auxPossibleClientStreams :: Aux -> IO Int

-- | "http" or "https".
type Scheme = ByteString

-- | Authority.
type Authority = String
type Method = ByteString

-- | Path.
type Path = ByteString

-- | File specification.
data FileSpec
FileSpec :: FilePath -> FileOffset -> ByteCount -> FileSpec

-- | Offset for file.
type FileOffset = Int64

-- | How many bytes to read
type ByteCount = Int64

-- | Naive implementation for readN.
--   
--   <i>NOTE</i>: This function is intended to be used by a single thread
--   only. (It is probably quite rare anyway to want concurrent reads from
--   the <i>same</i> network socket.)
defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN

-- | Reading n bytes.
type ReadN = Int -> IO ByteString

-- | Position read based on <a>Handle</a>.
defaultPositionReadMaker :: PositionReadMaker

-- | Position read for files.
type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount

-- | Making a position read and its closer.
type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
data Sentinel

-- | Closing a file resource. Its refresher is automatiaclly generated by
--   the internal timer.
Closer :: IO () -> Sentinel

-- | Refreshing a file resource while reading. Closing the file must be
--   done by its own timer or something.
Refresher :: IO () -> Sentinel

module Network.HTTP.Semantics.IO

-- | Naive implementation for readN.
--   
--   <i>NOTE</i>: This function is intended to be used by a single thread
--   only. (It is probably quite rare anyway to want concurrent reads from
--   the <i>same</i> network socket.)
defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN

-- | Reading n bytes.
type ReadN = Int -> IO ByteString

-- | Position read based on <a>Handle</a>.
defaultPositionReadMaker :: PositionReadMaker

-- | Position read for files.
type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount

-- | Making a position read and its closer.
type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
data Sentinel

-- | Closing a file resource. Its refresher is automatiaclly generated by
--   the internal timer.
Closer :: IO () -> Sentinel

-- | Refreshing a file resource while reading. Closing the file must be
--   done by its own timer or something.
Refresher :: IO () -> Sentinel
fillBuilderBodyGetNext :: Builder -> DynaNext
fillFileBodyGetNext :: PositionRead -> FileOffset -> ByteCount -> Sentinel -> DynaNext
fillStreamBodyGetNext :: IO (Maybe StreamingChunk) -> DynaNext
type BytesFilled = Int

-- | Action to run prior to terminating the stream
type CleanupStream = IO ()

-- | Write part of a streaming response to the write buffer
--   
--   In <tt>http2</tt> this will be used to construct a single HTTP2
--   <tt>DATA</tt> frame (see discussion of the maximum number of bytes,
--   below).
type DynaNext = Buffer -> Int -> IO Next
data IsEndOfStream

-- | The stream is not yet terminated
NotEndOfStream :: IsEndOfStream

-- | The stream is terminated
--   
--   In addition to indicating that the stream is terminated, we can also
--   specify an optional <tt>Cleanup</tt> handler to be run.
EndOfStream :: Maybe CleanupStream -> IsEndOfStream
data Next
Next :: BytesFilled -> Bool -> Maybe DynaNext -> Next
CancelNext :: Maybe SomeException -> Next
data StreamingChunk

-- | Indicate that the stream is finished
StreamingFinished :: Maybe CleanupStream -> StreamingChunk

-- | Indicate that the stream is cancelled
StreamingCancelled :: Maybe SomeException -> StreamingChunk

-- | Flush the stream
--   
--   This will cause the write buffer to be written to the network socket,
--   without waiting for more data.
StreamingFlush :: StreamingChunk

-- | Construct a DATA frame, optionally terminating the stream
StreamingBuilder :: Builder -> IsEndOfStream -> StreamingChunk

-- | TrailersMake to create no trailers.
defaultTrailersMaker :: TrailersMaker

-- | Running trailers-maker.
--   
--   <pre>
--   bufferIO buf siz $ \bs -&gt; tlrmkr (Just bs)
--   </pre>
runTrailersMaker :: TrailersMaker -> Buffer -> Int -> IO NextTrailersMaker

-- | Either the next trailers maker or final trailers.
data NextTrailersMaker
NextTrailersMaker :: TrailersMaker -> NextTrailersMaker
Trailers :: [Header] -> NextTrailersMaker

-- | Trailers maker. A chunks of the response body is passed with
--   <a>Just</a>. The maker should update internal state with the
--   <a>ByteString</a> and return the next trailers maker. When response
--   body reaches its end, <a>Nothing</a> is passed and the maker should
--   generate trailers. An example:
--   
--   <pre>
--   {-# 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 -&gt; Maybe ByteString -&gt; 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
--   </pre>
--   
--   Usage example:
--   
--   <pre>
--   let h2rsp = responseFile ...
--       maker = trailersMaker (CH.hashInit :: Context SHA1)
--       h2rsp' = setResponseTrailersMaker h2rsp maker
--   </pre>
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker
