| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
Ecluse.Runtime.Server
Description
The HTTP front door: the raw wai Application, its dispatch, the middleware stack, and
runWarp. It is a raw Application rather than a framework because matching on pathInfo
keeps the encoded-slash handling and the streaming control the proxy depends on
(docs/architecture/web-layer.md). Dispatch matches a request's leading segments to a
configured MountBinding, strips the prefix, and asks that mount's router what the remainder
names, so this module holds no path grammar and no status of its own. A path under no mount is
the neutral 404, and /livez and /readyz are answered above the mounts.
Synopsis
- data ServerConfig = ServerConfig {
- scPort :: Int
- scMounts :: [MountBinding]
- scDrainTimeout :: ShutdownDrainTimeout
- scCheckReady :: IO Readiness
- scCheckLive :: IO Liveness
- scOnException :: Maybe Request -> SomeException -> IO ()
- mkServerConfig :: [MountBinding] -> ServerConfig
- data MountBinding = MountBinding {
- bindingPrefix :: NonEmpty Text
- bindingRouter :: MountRouter
- bindingCredential :: CredentialMapping
- bindingPackumentDeps :: PackumentDeps
- bindingPublishDeps :: Maybe PublishDeps
- application :: ServerConfig -> Env -> Application
- tracedApplication :: ServerConfig -> Env -> IO Application
- runWarp :: LogEnv -> Text -> ServerConfig -> (ServerConfig -> IO Application) -> IO ()
- proxyListener :: Text
- serverModule :: Text
- listeningPrefix :: Text -> Text
- raceServerAgainstLoop :: MonadUnliftIO m => m () -> m () -> m ()
- probeApplication :: IO Readiness -> IO Liveness -> Application
- probeOnlyApplication :: Deadlines -> ServerConfig -> IO Application
- newtype ShutdownDrainTimeout = ShutdownDrainTimeout Int
- defaultShutdownDrainTimeout :: ShutdownDrainTimeout
- data InteractiveHalt = InteractiveHalt {
- haltOnInteractive :: IO Bool
- awaitHaltSignal :: IO ()
- halt :: IO ()
- defaultInteractiveHalt :: InteractiveHalt
- withInteractiveHalt :: InteractiveHalt -> IO a -> IO a
- serverMiddleware :: Deadlines -> Middleware
The WAI application
data ServerConfig Source #
The settings the web layer needs to serve that the composition-root Env does not carry.
Not the request-body cap: the publish route bounds its own body as a value.
Constructors
| ServerConfig | |
Fields
| |
mkServerConfig :: [MountBinding] -> ServerConfig Source #
Build a ServerConfig over the mount bindings on defaultPort. There is no built-in
mount: the web layer serves only the ecosystems the composition root binds here.
data MountBinding #
Constructors
| MountBinding | |
Fields
| |
application :: ServerConfig -> Env -> Application Source #
The proxy's WAI Application: the request dispatch under the cross-cutting
middleware stack (serverMiddleware).
tracedApplication :: ServerConfig -> Env -> IO Application Source #
application with the OpenTelemetry server-span middleware wrapped outermost, so
one server span covers the whole request. The wrapper is id when telemetry is off.
Running the server
runWarp :: LogEnv -> Text -> ServerConfig -> (ServerConfig -> IO Application) -> IO () Source #
Serve the application built from the config until SIGTERM or SIGINT, then let warp
finish in-flight requests within scDrainTimeout. On a TTY, Ctrl-D halts at once.
proxyListener :: Text Source #
The proxy's listener name, which starts the line it logs once bound.
serverModule :: Text Source #
The module field of the front door's own lines, named for the public module so an operator's saved filter keeps matching.
listeningPrefix :: Text -> Text Source #
The start of the line a named listener logs once bound, followed by the port.
raceServerAgainstLoop :: MonadUnliftIO m => m () -> m () -> m () Source #
Race a server arm against a never-returning background loop, the single-process shutdown
shape. race_ is the invariant: concurrently_ would wait forever, brackets un-unwound.
probeApplication :: IO Readiness -> IO Liveness -> Application Source #
The control-plane health probes, answered above any mount: /livez and /readyz from the
injected checks. Any other path is a 404.
probeOnlyApplication :: Deadlines -> ServerConfig -> IO Application Source #
The WAI Application of a role that serves the health probes and nothing else. Every
path outside /livez and /readyz is the neutral 404.
Graceful shutdown
newtype ShutdownDrainTimeout Source #
The bound on the graceful drain, in seconds. The server stops accepting connections, waits this long for in-flight requests and artifact streams, then exits regardless.
Constructors
| ShutdownDrainTimeout Int |
Instances
| Show ShutdownDrainTimeout Source # | |
Defined in Ecluse.Runtime.Server.Internal Methods showsPrec :: Int -> ShutdownDrainTimeout -> ShowS # show :: ShutdownDrainTimeout -> String # showList :: [ShutdownDrainTimeout] -> ShowS # | |
| Eq ShutdownDrainTimeout Source # | |
Defined in Ecluse.Runtime.Server.Internal Methods (==) :: ShutdownDrainTimeout -> ShutdownDrainTimeout -> Bool # (/=) :: ShutdownDrainTimeout -> ShutdownDrainTimeout -> Bool # | |
defaultShutdownDrainTimeout :: ShutdownDrainTimeout Source #
The default graceful-drain bound: 30 seconds. It covers an in-flight metadata fetch or a moderate artifact stream, and stops a stuck request pinning the old instance.
Local-dev immediate halt
data InteractiveHalt Source #
The local-development immediate-halt wiring, as injection points a test drives without a terminal. Ctrl-D exits the process at once and aborts the drain. It is inert on a non-TTY.
Constructors
| InteractiveHalt | |
Fields
| |
defaultInteractiveHalt :: InteractiveHalt Source #
The real local-dev halt: armed only on a terminal and fired by end-of-input, exiting at once without a drain. Status 130 is the conventional "terminated from the terminal" code.
withInteractiveHalt :: InteractiveHalt -> IO a -> IO a Source #
Run an action with the immediate-halt watcher armed only when haltOnInteractive is
True. The watcher lives exactly as long as the action, so it never outlives it.
Middleware
serverMiddleware :: Deadlines -> Middleware Source #
The cross-cutting stack around the proxy Application. The body cap is not a middleware:
it would throw across the request perimeter, and Autohead and Gzip fight streaming.