@@ -1,5 +1,27 @@
11{-# LANGUAGE OverloadedStrings, RankNTypes #-}
22{-# LANGUAGE CPP #-}
3+
4+-- | An HTTP\/2-aware variant of the 'Network.Wai.Application' type. Compared
5+-- to the original, this exposes the new functionality of server push and
6+-- trailers, allows stream fragments to be sent in the form of file ranges, and
7+-- allows the stream body to produce a value to be used in constructing the
8+-- trailers. Existing @Applications@ can be faithfully upgraded to HTTP\/2
9+-- with 'promoteApplication' or served transparently over both protocols with
10+-- the normal Warp 'Network.Wai.Handler.Warp.run' family of functions.
11+--
12+-- An 'HTTP2Application' takes a 'Request' and a 'PushFunc' and produces a
13+-- 'Responder' that will push any associated resources and send the response
14+-- body. The response is always a stream of 'Builder's and file chunks.
15+-- Equivalents of the 'Network.Wai.responseBuilder' family of functions are
16+-- provided for creating 'Responder's conveniently.
17+--
18+-- Pushed streams are handled by an IO action that triggers a server push. It
19+-- returns @True@ if the @PUSH_PROMISE@ frame was sent, @False@ if not. Note
20+-- this means it will still return @True@ if the client reset or ignored the
21+-- stream. This gives handlers the freedom to implement their own heuristics
22+-- for whether to actually push a resource, while also allowing middleware and
23+-- frameworks to trigger server pushes automatically.
24+
325module Network.Wai.HTTP2
426 (
527 -- * Applications