| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Network.HTTP2.Server
Description
HTTP/2 server library.
Example:
{-# LANGUAGE OverloadedStrings #-}
module Main (main) where
import qualified Control.Exception as E
import Data.ByteString.Builder (byteString)
import Network.HTTP.Types (ok200)
import Network.Run.TCP (runTCPServer) -- network-run
import Network.HTTP2.Server
main :: IO ()
main = runTCPServer Nothing "80" runHTTP2Server
where
runHTTP2Server s = E.bracket (allocSimpleConfig s 4096)
freeSimpleConfig
(\config -> run defaultServerConfig config server)
server _req _aux sendResponse = sendResponse response []
where
response = responseBuilder ok200 header body
header = [("Content-Type", "text/plain")]
body = byteString "Hello, world!\n"Synopsis
- run :: ServerConfig -> Config -> Server -> IO ()
- runWith :: STM () -> ServerConfig -> Config -> Server -> IO ()
- data ServerConfig
- defaultServerConfig :: ServerConfig
- numberOfWorkers :: ServerConfig -> Int
- connectionWindowSize :: ServerConfig -> WindowSize
- settings :: ServerConfig -> Settings
- data Settings
- defaultSettings :: Settings
- headerTableSize :: Settings -> Int
- enablePush :: Settings -> Bool
- maxConcurrentStreams :: Settings -> Maybe Int
- initialWindowSize :: Settings -> WindowSize
- maxFrameSize :: Settings -> Int
- maxHeaderListSize :: Settings -> Maybe Int
- pingRateLimit :: Settings -> Int
- settingsRateLimit :: Settings -> Int
- emptyFrameRateLimit :: Settings -> Int
- rstRateLimit :: Settings -> Int
- data Config
- defaultConfig :: Config
- confWriteBuffer :: Config -> Buffer
- confBufferSize :: Config -> BufferSize
- confSendAll :: Config -> ByteString -> IO ()
- confSendAllWith :: Config -> Maybe (STM () -> ByteString -> IO (Either () ()))
- confReadN :: Config -> Int -> IO ByteString
- confReadNWith :: Config -> Maybe (STM () -> Int -> IO ByteString)
- confPositionReadMaker :: Config -> PositionReadMaker
- confTimeoutManager :: Config -> Manager
- confMySockAddr :: Config -> SockAddr
- confPeerSockAddr :: Config -> SockAddr
- confReadNTimeout :: Config -> Bool
- confOnInformational :: Config -> StreamId -> TokenHeaderTable -> IO ()
- allocSimpleConfig :: Socket -> BufferSize -> IO Config
- allocSimpleConfig' :: Socket -> BufferSize -> Int -> IO Config
- allocSimpleConfigWith :: Socket -> BufferSize -> Int -> STM a -> IO Config
- freeSimpleConfig :: Config -> IO ()
- defaultPositionReadMaker :: PositionReadMaker
- defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN
- defaultReadNWith :: Socket -> IORef (Maybe ByteString) -> STM a -> ReadN
- defaultAux :: Aux
- getRequestBodyChunk :: Request -> IO ByteString
- getRequestBodyChunk' :: Request -> IO (ByteString, Bool)
- getRequestTrailers :: Request -> IO (Maybe TokenHeaderTable)
- pushPromise :: ByteString -> Response -> Int -> PushPromise
- requestAuthority :: Request -> Maybe Authority
- requestBodySize :: Request -> Maybe Int
- requestHeaders :: Request -> TokenHeaderTable
- requestMethod :: Request -> Maybe Method
- requestPath :: Request -> Maybe Path
- requestScheme :: Request -> Maybe Scheme
- responseBodySize :: Response -> Maybe Int
- responseBuilder :: Status -> ResponseHeaders -> Builder -> Response
- responseFile :: Status -> ResponseHeaders -> FileSpec -> Response
- responseNoBody :: Status -> ResponseHeaders -> Response
- responseStreaming :: Status -> ResponseHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Response
- responseStreamingIface :: Status -> ResponseHeaders -> (OutBodyIface -> IO ()) -> Response
- setResponseTrailersMaker :: Response -> TrailersMaker -> Response
- defaultTrailersMaker :: TrailersMaker
- type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount
- type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel)
- data Sentinel
- type ReadN = Int -> IO ByteString
- data PushPromise = PushPromise {
- promiseRequestPath :: ByteString
- promiseResponse :: Response
- type Server = Request -> Aux -> (Response -> [PushPromise] -> IO ()) -> IO ()
- data Aux
- data Request
- data Response
- data NextTrailersMaker
- type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker
- type Authority = String
- type ByteCount = Int64
- type FileOffset = Int64
- data FileSpec = FileSpec FilePath FileOffset ByteCount
- data OutBodyIface = OutBodyIface {
- outBodyUnmask :: forall x. IO x -> IO x
- outBodyPush :: Builder -> IO ()
- outBodyPushFinal :: Builder -> IO ()
- outBodyCancel :: Maybe SomeException -> IO ()
- outBodyFlush :: IO ()
- type Path = ByteString
- type Scheme = ByteString
Runner
runWith :: STM () -> ServerConfig -> Config -> Server -> IO () Source #
Like run, but the connection goes away once the STM action fires:
GOAWAY(NO_ERROR) at once, streams above it refused, and the
connection closed when those below it are done.
Since: 5.4.13
Server configuration
data ServerConfig Source #
Server configuration
Instances
| Eq ServerConfig Source # | |
Defined in Network.HTTP2.Server.Run | |
| Show ServerConfig Source # | |
Defined in Network.HTTP2.Server.Run Methods showsPrec :: Int -> ServerConfig -> ShowS show :: ServerConfig -> String showList :: [ServerConfig] -> ShowS | |
defaultServerConfig :: ServerConfig Source #
The default server config.
>>>defaultServerConfigServerConfig {numberOfWorkers = 8, connectionWindowSize = 16777216, settings = Settings {headerTableSize = 4096, enablePush = True, maxConcurrentStreams = Just 64, initialWindowSize = 262144, maxFrameSize = 16384, maxHeaderListSize = Just 65536, pingRateLimit = 10, emptyFrameRateLimit = 4, settingsRateLimit = 4, rstRateLimit = 4}}
numberOfWorkers :: ServerConfig -> Int Source #
Deprecated: No effect anymore
Deprecated field.
connectionWindowSize :: ServerConfig -> WindowSize Source #
The window size of incoming streams
settings :: ServerConfig -> Settings Source #
Settings
HTTP/2 setting
HTTP/2 settings. See https://datatracker.ietf.org/doc/html/rfc9113#name-defined-settings.
Instances
defaultSettings :: Settings Source #
The default settings.
>>>defaultSettingsSettings {headerTableSize = 4096, enablePush = True, maxConcurrentStreams = Just 64, initialWindowSize = 262144, maxFrameSize = 16384, maxHeaderListSize = Just 65536, pingRateLimit = 10, emptyFrameRateLimit = 4, settingsRateLimit = 4, rstRateLimit = 4}
headerTableSize :: Settings -> Int Source #
SETTINGS_HEADER_TABLE_SIZE
enablePush :: Settings -> Bool Source #
SETTINGS_ENABLE_PUSH
maxConcurrentStreams :: Settings -> Maybe Int Source #
SETTINGS_MAX_CONCURRENT_STREAMS
initialWindowSize :: Settings -> WindowSize Source #
SETTINGS_INITIAL_WINDOW_SIZE
maxFrameSize :: Settings -> Int Source #
SETTINGS_MAX_FRAME_SIZE
maxHeaderListSize :: Settings -> Maybe Int Source #
SETTINGS_MAX_HEADER_LIST_SIZE. Our own value is also enforced:
a field block whose decoded size (RFC 9113 section 6.5.2: the
length of each field's name plus its value plus 32) exceeds it
resets the stream. With Nothing, nothing is advertised but a
limit of 64 KiB is enforced all the same (CVE-2026-49975).
Rate limits
pingRateLimit :: Settings -> Int Source #
Maximum number of pings allowed per second (CVE-2019-9512)
settingsRateLimit :: Settings -> Int Source #
Maximum number of settings frames allowed per second (CVE-2019-9515)
emptyFrameRateLimit :: Settings -> Int Source #
Maximum number of empty data frames allowed per second (CVE-2019-9518)
rstRateLimit :: Settings -> Int Source #
Maximum number of streams reset per second, whether by the peer's RST_STREAM (CVE-2023-44487) or by ours in answer to a stream error the peer caused (CVE-2025-8671)
Common configuration
defaultConfig :: Config Source #
Default config. This is just a template to modify via field names. Don't use this without modifications.
confWriteBuffer :: Config -> Buffer Source #
This is used only by frameSender. This MUST be freed after frameSender is terminated.
confBufferSize :: Config -> BufferSize Source #
The size of the write buffer. We assume that the read buffer is the same size. So, this value is announced via SETTINGS_MAX_FRAME_SIZE to the peer.
confSendAll :: Config -> ByteString -> IO () Source #
Not used when confSendAllWith is Just. When replacing it in
a config which has one, e.g. from allocSimpleConfig, set
confSendAllWith to Nothing or to a send of the same kind.
confSendAllWith :: Config -> Maybe (STM () -> ByteString -> IO (Either () ())) Source #
confSendAll which the library can give up on: Left when the
STM action fires first. With it, a write which the peer does
not read is ended by the timeout rather than by killing a thread.
Part of the data may have gone, so the connection is closed after.
Since: 5.4.13
confReadN :: Config -> Int -> IO ByteString Source #
When confReadNWith is Just, frames are read with it and only
the connection preface with this. When replacing it in a config
which has one, e.g. from allocSimpleConfig, set confReadNWith
to Nothing or to a read of the same kind sharing its buffer.
confReadNWith :: Config -> Maybe (STM () -> Int -> IO ByteString) Source #
confTimeoutManager :: Config -> Manager Source #
confMySockAddr :: Config -> SockAddr Source #
This is copied into Aux, if exist, on server.
confPeerSockAddr :: Config -> SockAddr Source #
This is copied into Aux, if exist, on server.
confReadNTimeout :: Config -> Bool Source #
confOnInformational :: Config -> StreamId -> TokenHeaderTable -> IO () Source #
Client only: called when a 1xx informational response (e.g. 103 Early Hints) is received on the given stream, ahead of the final response. No-op by default.
Since: 5.4.2
allocSimpleConfig :: Socket -> BufferSize -> IO Config Source #
Making simple configuration whose IO is not efficient. A write buffer is allocated internally. WAI timeout manger is initialized with 30_000_000 microseconds.
allocSimpleConfig' :: Socket -> BufferSize -> Int -> IO Config Source #
Making simple configuration whose IO is not efficient. A write buffer is allocated internally. The third argument is microseconds to initialize WAI timeout manager.
allocSimpleConfigWith :: Socket -> BufferSize -> Int -> STM a -> IO Config Source #
allocSimpleConfig' whose receive the caller can give up on. The
STM action is waited for beside each receive; when it fires, the
reader ends as it does at end of input. Nothing is closed and no
thread is interrupted to make it return.
It also fills confSendAllWith and confReadNWith (since 5.4.13), so
that the library can give up on a send or a read in the same way.
Since: 5.4.11
freeSimpleConfig :: Config -> IO () Source #
Deallocating the resource of the simple configuration.
This does not cancel timeout actions registered with
confTimeoutManager. Since time-manager 0.3, a manager holds no
registrations, so there is nothing to kill: an action registered with
register runs even after this returns unless it
is cancelled with cancel. Use
withHandle, which cancels it when the scope ends.
defaultReadN :: Socket -> IORef (Maybe ByteString) -> ReadN #
defaultReadNWith :: Socket -> IORef (Maybe ByteString) -> STM a -> ReadN #
defaultAux :: Aux #
getRequestBodyChunk :: Request -> IO ByteString #
getRequestBodyChunk' :: Request -> IO (ByteString, Bool) #
getRequestTrailers :: Request -> IO (Maybe TokenHeaderTable) #
pushPromise :: ByteString -> Response -> Int -> PushPromise #
requestAuthority :: Request -> Maybe Authority #
requestBodySize :: Request -> Maybe Int #
requestMethod :: Request -> Maybe Method #
requestPath :: Request -> Maybe Path #
requestScheme :: Request -> Maybe Scheme #
responseBodySize :: Response -> Maybe Int #
responseBuilder :: Status -> ResponseHeaders -> Builder -> Response #
responseFile :: Status -> ResponseHeaders -> FileSpec -> Response #
responseNoBody :: Status -> ResponseHeaders -> Response #
responseStreaming :: Status -> ResponseHeaders -> ((Builder -> IO ()) -> IO () -> IO ()) -> Response #
responseStreamingIface :: Status -> ResponseHeaders -> (OutBodyIface -> IO ()) -> Response #
type PositionRead = FileOffset -> ByteCount -> Buffer -> IO ByteCount #
type PositionReadMaker = FilePath -> IO (PositionRead, Sentinel) #
data PushPromise #
Constructors
| PushPromise | |
Fields
| |
data NextTrailersMaker #
Constructors
| NextTrailersMaker TrailersMaker | |
| Trailers [Header] |
type TrailersMaker = Maybe ByteString -> IO NextTrailersMaker #
type FileOffset = Int64 #
Constructors
| FileSpec FilePath FileOffset ByteCount |
Instances
data OutBodyIface #
Constructors
| OutBodyIface | |
Fields
| |