1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
{-# LANGUAGE RankNTypes #-}
module Network.HTTP.Semantics.Types (
-- * Request/response as input
InpObj (..),
InpBody,
-- * Request/response as output
OutObj (..),
OutBody (..),
OutBodyIface (..),
-- * Trailers maker
TrailersMaker,
defaultTrailersMaker,
NextTrailersMaker (..),
-- * File spec
FileOffset,
ByteCount,
FileSpec (..),
-- * Types
Scheme,
Authority,
Path,
) where
import Control.Exception (SomeException)
import Data.ByteString.Builder (Builder)
import Data.IORef
import Data.Int (Int64)
import Network.ByteOrder
import qualified Network.HTTP.Types as H
import Network.HTTP.Semantics.Header
import Network.HTTP.Semantics.Trailer
----------------------------------------------------------------
-- | "http" or "https".
type Scheme = ByteString
-- | Authority.
type Authority = String
-- | Path.
type Path = ByteString
----------------------------------------------------------------
type InpBody = IO (ByteString, Bool)
data OutBody
= OutBodyNone
| -- | Streaming body takes a write action and a flush action.
OutBodyStreaming ((Builder -> IO ()) -> IO () -> IO ())
| -- | Generalization of 'OutBodyStreaming'.
OutBodyStreamingIface (OutBodyIface -> IO ())
| OutBodyBuilder Builder
| OutBodyFile FileSpec
data OutBodyIface = OutBodyIface
{ 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.
}
-- | Input object
data InpObj = InpObj
{ 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.
}
instance Show InpObj where
show (InpObj (thl, _) _ _body _tref) = show thl
-- | Output object
data OutObj = OutObj
{ outObjHeaders :: [H.Header]
-- ^ Accessor for header.
, outObjBody :: OutBody
-- ^ Accessor for outObj body.
, outObjTrailers :: TrailersMaker
-- ^ Accessor for trailers maker.
}
instance Show OutObj where
show (OutObj hdr _ _) = show hdr
----------------------------------------------------------------
-- | Offset for file.
type FileOffset = Int64
-- | How many bytes to read
type ByteCount = Int64
-- | File specification.
data FileSpec = FileSpec FilePath FileOffset ByteCount deriving (Eq, Show)
|
