Debian Codegraph @

src/Network/WebSockets/Connection/Options.hs

raw
1 {-# LANGUAGE CPP #-}
2 --------------------------------------------------------------------------------
3 module Network.WebSockets.Connection.Options
4 ( ConnectionOptions (..)
5 , defaultConnectionOptions
6
7 , CompressionOptions (..)
8 , PermessageDeflate (..)
9 , defaultPermessageDeflate
10
11 , SizeLimit (..)
12 , atMostSizeLimit
13 ) where
14
15
16 --------------------------------------------------------------------------------
17 import Data.Int (Int64)
18 import Data.Monoid (Monoid (..))
19 import Prelude
20
21
22 --------------------------------------------------------------------------------
23 -- | Set options for a 'Connection'. Please do not use this constructor
24 -- directly, but rather use 'defaultConnectionOptions' and then set the fields
25 -- you want, e.g.:
26 --
27 -- > myOptions = defaultConnectionOptions {connectionStrictUnicode = True}
28 --
29 -- This way your code does not break if the library introduces new fields.
30 data ConnectionOptions = ConnectionOptions
31 { connectionOnPong :: !(IO ())
32 -- ^ Whenever a 'pong' is received, this IO action is executed. It can be
33 -- used to tickle connections or fire missiles.
34 , connectionTimeout :: !Int
35 -- ^ Timeout for connection establishment in seconds. Only used in the client.
36 , connectionCompressionOptions :: !CompressionOptions
37 -- ^ Enable 'PermessageDeflate'.
38 , connectionStrictUnicode :: !Bool
39 -- ^ Enable strict unicode on the connection. This means that if a client
40 -- (or server) sends invalid UTF-8, we will throw a 'UnicodeException'
41 -- rather than replacing it by the unicode replacement character U+FFFD.
42 , connectionFramePayloadSizeLimit :: !SizeLimit
43 -- ^ The maximum size for incoming frame payload size in bytes. If a
44 -- frame exceeds this limit, a 'ParseException' is thrown.
45 , connectionMessageDataSizeLimit :: !SizeLimit
46 -- ^ 'connectionFrameSizeLimit' is often not enough since a malicious
47 -- client can send many small frames to create a huge message. This limit
48 -- allows you to protect from that. If a message exceeds this limit, a
49 -- 'ParseException' is thrown.
50 --
51 -- Note that, if compression is enabled, we check the size of the
52 -- compressed messages, as well as the size of the uncompressed messages
53 -- as we are deflating them to ensure we don't use too much memory in any
54 -- case.
55 }
56
57
58 --------------------------------------------------------------------------------
59 -- | The default connection options:
60 --
61 -- * Nothing happens when a pong is received.
62 -- * Compression is disabled.
63 -- * Lenient unicode decoding.
64 -- * 30 second timeout for connection establishment.
65 defaultConnectionOptions :: ConnectionOptions
66 defaultConnectionOptions = ConnectionOptions
67 { connectionOnPong = return ()
68 , connectionTimeout = 30
69 , connectionCompressionOptions = NoCompression
70 , connectionStrictUnicode = False
71 , connectionFramePayloadSizeLimit = mempty
72 , connectionMessageDataSizeLimit = mempty
73 }
74
75
76 --------------------------------------------------------------------------------
77 data CompressionOptions
78 = NoCompression
79 | PermessageDeflateCompression PermessageDeflate
80 deriving (Eq, Show)
81
82
83 --------------------------------------------------------------------------------
84 -- | Four extension parameters are defined for "permessage-deflate" to
85 -- help endpoints manage per-connection resource usage.
86 --
87 -- - "server_no_context_takeover"
88 -- - "client_no_context_takeover"
89 -- - "server_max_window_bits"
90 -- - "client_max_window_bits"
91 data PermessageDeflate = PermessageDeflate
92 { serverNoContextTakeover :: Bool
93 , clientNoContextTakeover :: Bool
94 , serverMaxWindowBits :: Int
95 , clientMaxWindowBits :: Int
96 , pdCompressionLevel :: Int
97 } deriving (Eq, Show)
98
99
100 --------------------------------------------------------------------------------
101 defaultPermessageDeflate :: PermessageDeflate
102 defaultPermessageDeflate = PermessageDeflate False False 15 15 8
103
104
105 --------------------------------------------------------------------------------
106 -- | A size limit, in bytes. The 'Monoid' instance takes the minimum limit.
107 data SizeLimit
108 = NoSizeLimit
109 | SizeLimit !Int64
110 deriving (Eq, Show)
111
112
113 --------------------------------------------------------------------------------
114 instance Monoid SizeLimit where
115 mempty = NoSizeLimit
116
117 #if !MIN_VERSION_base(4,11,0)
118 mappend NoSizeLimit y = y
119 mappend x NoSizeLimit = x
120 mappend (SizeLimit x) (SizeLimit y) = SizeLimit (min x y)
121 #else
122 instance Semigroup SizeLimit where
123 (<>) NoSizeLimit y = y
124 (<>) x NoSizeLimit = x
125 (<>) (SizeLimit x) (SizeLimit y) = SizeLimit (min x y)
126 #endif
127
128 --------------------------------------------------------------------------------
129 atMostSizeLimit :: Int64 -> SizeLimit -> Bool
130 atMostSizeLimit _ NoSizeLimit = True
131 atMostSizeLimit s (SizeLimit l) = s <= l
132 {-# INLINE atMostSizeLimit #-}