@@ -67,14 +67,14 @@ allowInterrupt :: IO ()
67allowInterrupt = unblock $ return ()
67allowInterrupt = unblock $ return ()
70−-- | Run an 'Application' on the given port. This calls 'runSettings' with
70+-- | Run an 'Application' on the given port.
71−-- 'defaultSettings'.
71+-- This calls 'runSettings' with 'defaultSettings'.
72run :: Port -> Application -> IO ()
72run :: Port -> Application -> IO ()
73run p = runSettings defaultSettings { settingsPort = p }
73run p = runSettings defaultSettings { settingsPort = p }
75−-- | Run an 'Application' on the port present in the @PORT@ environment variable
75+-- | Run an 'Application' on the port present in the @PORT@
77−-- Uses the 'Port' given when the variable is unset.
76+-- environment variable. Uses the 'Port' given when the variable is unset.
77+-- This calls 'runSettings' with 'defaultSettings'.
79-- Since 3.0.9
79-- Since 3.0.9
80runEnv :: Port -> Application -> IO ()
80runEnv :: Port -> Application -> IO ()
@@ -90,6 +90,8 @@ runEnv p app = do
90 _ -> fail $ "Invalid value in $PORT: " ++ sp
90 _ -> fail $ "Invalid value in $PORT: " ++ sp
92-- | Run an 'Application' with the given 'Settings'.
92-- | Run an 'Application' with the given 'Settings'.
93+-- This opens a listen socket on the port defined in 'Settings' and
94+-- calls 'runSettingsSocket'.
93runSettings :: Settings -> Application -> IO ()
95runSettings :: Settings -> Application -> IO ()
94runSettings set app = withSocketsDo $
96runSettings set app = withSocketsDo $
@@ -99,15 +101,17 @@ runSettings set app = withSocketsDo $
99 setSocketCloseOnExec socket
101 setSocketCloseOnExec socket
100 runSettingsSocket set socket app)
102 runSettingsSocket set socket app)
102−-- | Same as 'runSettings', but uses a user-supplied socket instead of opening
104+-- | This installs a shutdown handler for the given socket and
103−-- one. This allows the user to provide, for example, Unix named socket, which
105+-- calls 'runSettingsConnection' with the default connection setup action
106+-- which handles plain (non-cipher) HTTP.
107+-- When the listen socket in the second argument is closed, all live
108+-- connections are gracefully shut down.
110+-- The supplied socket can be a Unix named socket, which
104-- can be used when reverse HTTP proxying into your application.
111-- can be used when reverse HTTP proxying into your application.
106-- Note that the 'settingsPort' will still be passed to 'Application's via the
113-- Note that the 'settingsPort' will still be passed to 'Application's via the
107-- 'serverPort' record.
114-- 'serverPort' record.
109−-- When the listen socket in the second argument is closed, all live
110−-- connections are gracefully shut down.
111runSettingsSocket :: Settings -> Socket -> Application -> IO ()
115runSettingsSocket :: Settings -> Socket -> Application -> IO ()
112runSettingsSocket set socket app = do
116runSettingsSocket set socket app = do
113 settingsInstallShutdownHandler set closeListenSocket
117 settingsInstallShutdownHandler set closeListenSocket
@@ -125,10 +129,13 @@ runSettingsSocket set socket app = do
126 closeListenSocket = sClose socket
130 closeListenSocket = sClose socket
128−-- | Allows you to provide a function which will return a 'Connection'. In
132+-- | The connection setup action would be expensive. An good example
129−-- cases where creating the @Connection@ can be expensive, this allows the
133+-- is initialization of TLS.
134+-- So, this convers the connection setup action to the connection maker
135+-- which will be executed after forking a new worker thread.
136+-- Then this calles 'runSettingsConnectionMaker' with the connection maker.
130−-- expensive computations to be performed in a separate thread instead of the
137+-- This allows the expensive computations to be performed
131−-- main server loop.
138+-- in a separate worker thread instead of the main server loop.
133-- Since 1.3.5
140-- Since 1.3.5
134runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()
141runSettingsConnection :: Settings -> IO (Connection, SockAddr) -> Application -> IO ()
@@ -138,6 +145,8 @@ runSettingsConnection set getConn app = runSettingsConnectionMaker set getConnMa
138 (conn, sa) <- getConn
145 (conn, sa) <- getConn
139 return (return conn, sa)
146 return (return conn, sa)
148+-- | This modifies the connection maker so that it returns 'TCP' for 'Transport'
149+-- (i.e. plain HTTP) then calls 'runSettingsConnectionMakerSecure'.
141runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()
150runSettingsConnectionMaker :: Settings -> IO (IO Connection, SockAddr) -> Application -> IO ()
142runSettingsConnectionMaker x y =
151runSettingsConnectionMaker x y =
143 runSettingsConnectionMakerSecure x (go y)
152 runSettingsConnectionMakerSecure x (go y)
@@ -146,8 +155,10 @@ runSettingsConnectionMaker x y =
147----------------------------------------------------------------
156----------------------------------------------------------------
149−-- | Allows you to provide a function which will return a function
158+-- | The core run function which takes 'Settings',
150−-- which will return 'Connection'.
159+-- a connection maker and 'Application'.
160+-- The connection maker can return a connection of either plain HTTP
152-- Since 2.1.4
163-- Since 2.1.4
153runSettingsConnectionMakerSecure :: Settings -> IO (IO (Connection, Transport), SockAddr) -> Application -> IO ()
164runSettingsConnectionMakerSecure :: Settings -> IO (IO (Connection, Transport), SockAddr) -> Application -> IO ()