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 Source #

How many bytes to read

type FileOffset = Int64 Source #

Offset for file.

data OutBodyIface Source #

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 Source #

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 Source #

Either the next trailers maker or final trailers.

Constructors

NextTrailersMaker TrailersMaker |
Trailers [Header] |

defaultTrailersMaker :: TrailersMaker Source #

TrailersMake to create no trailers.

type Scheme = ByteString Source #

"http" or "https".

type Authority = String Source #

Authority.

type Path = ByteString Source #

Path.

data FileSpec Source #

File specification.

Constructors

FileSpec FilePath FileOffset ByteCount |

#### Instances

Instances details

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

data InpObj Source #

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 Source # |
Instance details Defined in Network.HTTP.Semantics.Types Methods showsPrec :: Int -> InpObj -> ShowS Source # show :: InpObj -> String Source # showList :: [InpObj] -> ShowS Source #

data OutObj Source #

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 Source # |
Instance details Defined in Network.HTTP.Semantics.Types Methods showsPrec :: Int -> OutObj -> ShowS Source # show :: OutObj -> String Source # showList :: [OutObj] -> ShowS Source #

type InpBody = IO (ByteString, Bool) Source #

data OutBody Source #

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 Source #

Field name. Internal usage only.

type FieldValue = ByteString Source #

Field value.

type TokenHeader = (Token, FieldValue) Source #

TokenBased header.

type TokenHeaderList = [TokenHeader] Source #

TokenBased header list.

type TokenHeaderTable = (TokenHeaderList, ValueTable) Source #

A pair of token list and value table.

type ValueTable = Array Int (Maybe FieldValue) Source #

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

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

Accessing `FieldValue` with `Token`.

type HeaderTable = (TokenHeaderList, ValueTable) Source #

Deprecated: use TokenHeaderTable instead

A pair of token list and value table.

type HeaderValue = ByteString Source #

Deprecated: use FieldValue instead

Header value.

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

Deprecated: use geFieldValue instead

Accessing `FieldValue` with `Token`.

data Token Source #

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

tokenCIKey :: Token -> ByteString Source #

Extracting a case insensitive header key from a token.

tokenFoldedKey :: Token -> ByteString Source #

Extracting a folded header key from a token.

toToken :: ByteString -> Token Source #

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 Source #

Minimum token index.

maxStaticTokenIx :: Int Source #

Maximun token index defined in the static table.

maxTokenIx :: Int Source #

Maximum token index.

cookieTokenIx :: Int Source #

Token index for `tokenCookie`.

isMaxTokenIx :: Int -> Bool Source #

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

isCookieTokenIx :: Int -> Bool Source #

Is this token ix for Cookie?

isStaticTokenIx :: Int -> Bool Source #

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

isStaticToken :: Token -> Bool Source #

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

tokenAuthority :: Token Source #

tokenMethod :: Token Source #

tokenPath :: Token Source #

tokenScheme :: Token Source #

tokenStatus :: Token Source #

tokenAcceptCharset :: Token Source #

tokenAcceptEncoding :: Token Source #

tokenAcceptLanguage :: Token Source #

tokenAcceptRanges :: Token Source #

tokenAccept :: Token Source #

tokenAccessControlAllowOrigin :: Token Source #

tokenAge :: Token Source #

tokenAllow :: Token Source #

tokenAuthorization :: Token Source #

tokenCacheControl :: Token Source #

tokenContentDisposition :: Token Source #

tokenContentEncoding :: Token Source #

tokenContentLanguage :: Token Source #

tokenContentLength :: Token Source #

tokenContentLocation :: Token Source #

tokenContentRange :: Token Source #

tokenContentType :: Token Source #

tokenCookie :: Token Source #

tokenDate :: Token Source #

tokenEtag :: Token Source #

tokenExpect :: Token Source #

tokenExpires :: Token Source #

tokenFrom :: Token Source #

tokenHost :: Token Source #

tokenIfMatch :: Token Source #

tokenIfModifiedSince :: Token Source #

tokenIfNoneMatch :: Token Source #

tokenIfRange :: Token Source #

tokenIfUnmodifiedSince :: Token Source #

tokenLastModified :: Token Source #

tokenLink :: Token Source #

tokenLocation :: Token Source #

tokenMaxForwards :: Token Source #

tokenProxyAuthenticate :: Token Source #

tokenProxyAuthorization :: Token Source #

tokenRange :: Token Source #

tokenReferer :: Token Source #

tokenRefresh :: Token Source #

tokenRetryAfter :: Token Source #

tokenServer :: Token Source #

tokenSetCookie :: Token Source #

tokenStrictTransportSecurity :: Token Source #

tokenTransferEncoding :: Token Source #

tokenUserAgent :: Token Source #

tokenVary :: Token Source #

tokenVia :: Token Source #

tokenWwwAuthenticate :: Token Source #

tokenConnection :: Token Source #

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

tokenTE :: Token Source #

tokenMax :: Token Source #

tokenAccessControlAllowCredentials :: Token Source #

For QPACK

tokenAccessControlAllowHeaders :: Token Source #

tokenAccessControlAllowMethods :: Token Source #

tokenAccessControlExposeHeaders :: Token Source #

tokenAccessControlRequestHeaders :: Token Source #

tokenAccessControlRequestMethod :: Token Source #

tokenAltSvc :: Token Source #

tokenContentSecurityPolicy :: Token Source #

tokenEarlyData :: Token Source #

tokenExpectCt :: Token Source #

tokenForwarded :: Token Source #

tokenOrigin :: Token Source #

tokenPurpose :: Token Source #

tokenTimingAllowOrigin :: Token Source #

tokenUpgradeInsecureRequests :: Token Source #

tokenXContentTypeOptions :: Token Source #

tokenXForwardedFor :: Token Source #

tokenXFrameOptions :: Token Source #

tokenXXssProtection :: Token Source #