Network.HTTP.Semantics

http-semantics-0.3.0: HTTP senmatics libarry

Safe Haskell | None
Language | Haskell2010

Network.HTTP.Semantics

Description

Library for HTTP Semantics (RFC9110), version-independent common parts. For low-level headers, `Token` is used. For upper-level headers, `HeaderName` should be used.

Synopsis

- type ByteCount = Int64
- type FileOffset = Int64
- data OutBodyIface = OutBodyIface {
  - outBodyUnmask :: forall x. IO x -> IO x
  - outBodyPush :: Builder -> IO ()
  - outBodyPushFinal :: Builder -> IO ()
  - outBodyCancel :: Maybe SomeException -> IO ()
  - outBodyFlush :: IO ()
  }
- type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker
- data NextTrailersMaker
  - = NextTrailersMaker TrailersMaker
  - | Trailers [Header]
- defaultTrailersMaker :: TrailersMaker
- type Scheme = ByteString
- type Authority = String
- type Path = ByteString
- data FileSpec = FileSpec FilePath FileOffset ByteCount
- data InpObj = InpObj {
  - inpObjHeaders :: TokenHeaderTable
  - inpObjBodySize :: Maybe Int
  - inpObjBody :: InpBody
  - inpObjTrailers :: IORef (Maybe TokenHeaderTable)
  }
- data OutObj = OutObj {
  - outObjHeaders :: [Header]
  - outObjBody :: OutBody
  - outObjTrailers :: TrailersMaker
  }
- type InpBody = IO (ByteString, Bool)
- data OutBody
  - = OutBodyNone
  - | OutBodyStreaming ((Builder -> IO ()) -> IO () -> IO ())
  - | OutBodyStreamingIface (OutBodyIface -> IO ())
  - | OutBodyBuilder Builder
  - | OutBodyFile FileSpec
- type FieldName = ByteString
- type FieldValue = ByteString
- type TokenHeader = (Token, FieldValue)
- type TokenHeaderList = [TokenHeader]
- type TokenHeaderTable = (TokenHeaderList, ValueTable)
- type ValueTable = Array Int (Maybe FieldValue)
- getFieldValue :: Token -> ValueTable -> Maybe FieldValue
- type HeaderTable = (TokenHeaderList, ValueTable)
- type HeaderValue = ByteString
- getHeaderValue :: Token -> ValueTable -> Maybe FieldValue
- data Token = Token {
  - tokenIx :: Int
  - shouldBeIndexed :: Bool
  - isPseudo :: Bool
  - tokenKey :: HeaderName
  }
- tokenCIKey :: Token -> ByteString
- tokenFoldedKey :: Token -> ByteString
- toToken :: ByteString -> Token
- minTokenIx :: Int
- maxStaticTokenIx :: Int
- maxTokenIx :: Int
- cookieTokenIx :: Int
- isMaxTokenIx :: Int -> Bool
- isCookieTokenIx :: Int -> Bool
- isStaticTokenIx :: Int -> Bool
- isStaticToken :: Token -> Bool
- tokenAuthority :: Token
- tokenMethod :: Token
- tokenPath :: Token
- tokenScheme :: Token
- tokenStatus :: Token
- tokenAcceptCharset :: Token
- tokenAcceptEncoding :: Token
- tokenAcceptLanguage :: Token
- tokenAcceptRanges :: Token
- tokenAccept :: Token
- tokenAccessControlAllowOrigin :: Token
- tokenAge :: Token
- tokenAllow :: Token
- tokenAuthorization :: Token
- tokenCacheControl :: Token
- tokenContentDisposition :: Token
- tokenContentEncoding :: Token
- tokenContentLanguage :: Token
- tokenContentLength :: Token
- tokenContentLocation :: Token
- tokenContentRange :: Token
- tokenContentType :: Token
- tokenCookie :: Token
- tokenDate :: Token
- tokenEtag :: Token
- tokenExpect :: Token
- tokenExpires :: Token
- tokenFrom :: Token
- tokenHost :: Token
- tokenIfMatch :: Token
- tokenIfModifiedSince :: Token
- tokenIfNoneMatch :: Token
- tokenIfRange :: Token
- tokenIfUnmodifiedSince :: Token
- tokenLastModified :: Token
- tokenLink :: Token
- tokenLocation :: Token
- tokenMaxForwards :: Token
- tokenProxyAuthenticate :: Token
- tokenProxyAuthorization :: Token
- tokenRange :: Token
- tokenReferer :: Token
- tokenRefresh :: Token
- tokenRetryAfter :: Token
- tokenServer :: Token
- tokenSetCookie :: Token
- tokenStrictTransportSecurity :: Token
- tokenTransferEncoding :: Token
- tokenUserAgent :: Token
- tokenVary :: Token
- tokenVia :: Token
- tokenWwwAuthenticate :: Token
- tokenConnection :: Token
- tokenTE :: Token
- tokenMax :: Token
- tokenAccessControlAllowCredentials :: Token
- tokenAccessControlAllowHeaders :: Token
- tokenAccessControlAllowMethods :: Token
- tokenAccessControlExposeHeaders :: Token
- tokenAccessControlRequestHeaders :: Token
- tokenAccessControlRequestMethod :: Token
- tokenAltSvc :: Token
- tokenContentSecurityPolicy :: Token
- tokenEarlyData :: Token
- tokenExpectCt :: Token
- tokenForwarded :: Token
- tokenOrigin :: Token
- tokenPurpose :: Token
- tokenTimingAllowOrigin :: Token
- tokenUpgradeInsecureRequests :: Token
- tokenXContentTypeOptions :: Token
- tokenXForwardedFor :: Token
- tokenXFrameOptions :: Token
- tokenXXssProtection :: Token

# Documentation

type ByteCount = Int64 #

How many bytes to read

type FileOffset = Int64 #

Offset for file.

data OutBodyIface #

Constructors

OutBodyIface |
Fields outBodyUnmask :: forall x. IO x -> IO x 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 `OutBodyStreamingIface` 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. outBodyPush :: Builder -> IO () Push a new chunk In `http2`, there is no direct correspondence between chunks and the resulting `DATA` frames sent: the chunks are collected (written to an internal write buffer) until we can fill a frame. See also `outBodyFlush`. outBodyPushFinal :: Builder -> IO () Push the final chunk Using this function instead of `outBodyPush` can be used to guarantee that the final HTTP2 DATA frame is marked end-of-stream; with `outBodyPush` it may happen that an additional empty DATA frame is used for this purpose. Additionally, after calling this function, `outBodyCancel` will be a no-op. outBodyCancel :: Maybe SomeException -> IO () Cancel the stream Sends a `RST_STREAM` to the peer. If cancelling as the result of an exception, a `Just` 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 `RST_STREAM` will be `INTERNAL_ERROR` (see https://datatracker.ietf.org/doc/html/rfc7540#section-7). If `Nothing` is given, the error code will be `CANCEL`. If there is a partially constructed `DATA` frame at the time of cancellation, this frame is discarded. If this is undesirable, you should call `outBodyFlush` prior to cancelling. outBodyFlush :: IO () Flush This can be used to emit a DATA frame with the data collected so far (using `outBodyPush`), even if that DATA frame has not yet reached the maximum frame size. Calling `outBodyFlush` unnecessarily can therefore result in excessive overhead from frame headers. If no data is available to send, this is a no-op.

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.

type Scheme = ByteString #

"http" or "https".

type Authority = String #

Authority.

type Path = ByteString #

Path.

data FileSpec #

File specification.

Constructors

FileSpec FilePath FileOffset ByteCount |

#### Instances

Instances details

Show FileSpec # |
Instance details Defined in Network.HTTP.Semantics.Types Methods showsPrec :: Int -> FileSpec -> ShowS # show :: FileSpec -> String # showList :: [FileSpec] -> ShowS #
Eq FileSpec # |
Instance details Defined in Network.HTTP.Semantics.Types Methods (==) :: FileSpec -> FileSpec -> Bool # (/=) :: FileSpec -> FileSpec -> Bool #

data InpObj #

Input object

Constructors

InpObj |
Fields inpObjHeaders :: TokenHeaderTable Accessor for headers. inpObjBodySize :: Maybe Int Accessor for body length specified in content-length:. inpObjBody :: InpBody Accessor for body. inpObjTrailers :: IORef (Maybe TokenHeaderTable) Accessor for trailers.

#### Instances

Instances details

Show InpObj # |
Instance details Defined in Network.HTTP.Semantics.Types Methods showsPrec :: Int -> InpObj -> ShowS # show :: InpObj -> String # showList :: [InpObj] -> ShowS #

data OutObj #

Output object

Constructors

OutObj |
Fields outObjHeaders :: [Header] Accessor for header. outObjBody :: OutBody Accessor for outObj body. outObjTrailers :: TrailersMaker Accessor for trailers maker.

#### Instances

Instances details

Show OutObj # |
Instance details Defined in Network.HTTP.Semantics.Types Methods showsPrec :: Int -> OutObj -> ShowS # show :: OutObj -> String # showList :: [OutObj] -> ShowS #

type InpBody = IO (ByteString, Bool) #

data OutBody #

Constructors

OutBodyNone |
OutBodyStreaming ((Builder -> IO ()) -> IO () -> IO ()) | Streaming body takes a write action and a flush action.
OutBodyStreamingIface (OutBodyIface -> IO ()) | Generalization of `OutBodyStreaming`.
OutBodyBuilder Builder |
OutBodyFile FileSpec |

type FieldName = ByteString #

Field name. Internal usage only.

type FieldValue = ByteString #

Field value.

type TokenHeader = (Token, FieldValue) #

TokenBased header.

type TokenHeaderList = [TokenHeader] #

TokenBased header list.

type TokenHeaderTable = (TokenHeaderList, ValueTable) #

A pair of token list and value table.

type ValueTable = Array Int (Maybe FieldValue) #

An array to get `FieldValue` quickly. `getHeaderValue` should be used. Internally, the key is `tokenIx`.

getFieldValue :: Token -> ValueTable -> Maybe FieldValue #

Accessing `FieldValue` with `Token`.

type HeaderTable = (TokenHeaderList, ValueTable) #

Deprecated: use TokenHeaderTable instead

A pair of token list and value table.

type HeaderValue = ByteString #

Deprecated: use FieldValue instead

Header value.

getHeaderValue :: Token -> ValueTable -> Maybe FieldValue #

Deprecated: use geFieldValue instead

Accessing `FieldValue` with `Token`.

data Token #

Internal representation for header keys.

Constructors

Token |
Fields tokenIx :: Int Index for value table shouldBeIndexed :: Bool should be indexed in HPACK isPseudo :: Bool is this a pseudo header key? tokenKey :: HeaderName Case insensitive header key

#### Instances

Instances details

Show Token # |
Instance details Defined in Network.HTTP.Semantics.Token Methods showsPrec :: Int -> Token -> ShowS # show :: Token -> String # showList :: [Token] -> ShowS #
Eq Token # |
Instance details Defined in Network.HTTP.Semantics.Token Methods (==) :: Token -> Token -> Bool # (/=) :: Token -> Token -> Bool #

tokenCIKey :: Token -> ByteString #

Extracting a case insensitive header key from a token.

tokenFoldedKey :: Token -> ByteString #

Extracting a folded header key from a token.

toToken :: ByteString -> Token #

Making a token from a header key.

    >>> toToken ":authority" == tokenAuthority
    True
    >>> toToken "foo"
    Token {tokenIx = 73, shouldBeIndexed = True, isPseudo = False, tokenKey = "foo"}
    >>> toToken ":bar"
    Token {tokenIx = 73, shouldBeIndexed = True, isPseudo = True, tokenKey = ":bar"}

minTokenIx :: Int #

Minimum token index.

maxStaticTokenIx :: Int #

Maximun token index defined in the static table.

maxTokenIx :: Int #

Maximum token index.

cookieTokenIx :: Int #

Token index for `tokenCookie`.

isMaxTokenIx :: Int -> Bool #

Is this token ix to be held in the place holder?

isCookieTokenIx :: Int -> Bool #

Is this token ix for Cookie?

isStaticTokenIx :: Int -> Bool #

Is this token ix for a header not defined in the static table?

isStaticToken :: Token -> Bool #

Is this token for a header not defined in the static table?

tokenAuthority :: Token #

tokenMethod :: Token #

tokenPath :: Token #

tokenScheme :: Token #

tokenStatus :: Token #

tokenAcceptCharset :: Token #

tokenAcceptEncoding :: Token #

tokenAcceptLanguage :: Token #

tokenAcceptRanges :: Token #

tokenAccept :: Token #

tokenAccessControlAllowOrigin :: Token #

tokenAge :: Token #

tokenAllow :: Token #

tokenAuthorization :: Token #

tokenCacheControl :: Token #

tokenContentDisposition :: Token #

tokenContentEncoding :: Token #

tokenContentLanguage :: Token #

tokenContentLength :: Token #

tokenContentLocation :: Token #

tokenContentRange :: Token #

tokenContentType :: Token #

tokenCookie :: Token #

tokenDate :: Token #

tokenEtag :: Token #

tokenExpect :: Token #

tokenExpires :: Token #

tokenFrom :: Token #

tokenHost :: Token #

tokenIfMatch :: Token #

tokenIfModifiedSince :: Token #

tokenIfNoneMatch :: Token #

tokenIfRange :: Token #

tokenIfUnmodifiedSince :: Token #

tokenLastModified :: Token #

tokenLink :: Token #

tokenLocation :: Token #

tokenMaxForwards :: Token #

tokenProxyAuthenticate :: Token #

tokenProxyAuthorization :: Token #

tokenRange :: Token #

tokenReferer :: Token #

tokenRefresh :: Token #

tokenRetryAfter :: Token #

tokenServer :: Token #

tokenSetCookie :: Token #

tokenStrictTransportSecurity :: Token #

tokenTransferEncoding :: Token #

tokenUserAgent :: Token #

tokenVary :: Token #

tokenVia :: Token #

tokenWwwAuthenticate :: Token #

tokenConnection :: Token #

A place holder to hold header keys not defined in the static table. | For Warp

tokenTE :: Token #

tokenMax :: Token #

tokenAccessControlAllowCredentials :: Token #

For QPACK

tokenAccessControlAllowHeaders :: Token #

tokenAccessControlAllowMethods :: Token #

tokenAccessControlExposeHeaders :: Token #

tokenAccessControlRequestHeaders :: Token #

tokenAccessControlRequestMethod :: Token #

tokenAltSvc :: Token #

tokenContentSecurityPolicy :: Token #

tokenEarlyData :: Token #

tokenExpectCt :: Token #

tokenForwarded :: Token #

tokenOrigin :: Token #

tokenPurpose :: Token #

tokenTimingAllowOrigin :: Token #

tokenUpgradeInsecureRequests :: Token #

tokenXContentTypeOptions :: Token #

tokenXForwardedFor :: Token #

tokenXFrameOptions :: Token #

tokenXXssProtection :: Token #