Core.Webserver.Warp

Many programs present their interface in the form of a webservice, be it internet-facing, for internal use, or even just as a machine-local daemon. The Haskell language has numerous frameworks for building webservices and a number of high-quality HTTP server implementations. This module provides support for the Web Application Interface from the wai package and the warp webserver.

Given an Application type (the definition of your web service) and a Middleware (which is just Application -> Application), run a the Core.Program's Program monad. Metrics values (aka web server logs) will be sent as key/value pairs via Core.Telemetry.

Usage

First set up your program and initialize the telemetry subsystem.

import Core.Program
import Core.Telemetry
import Core.Webservice.Warp

main :: IO ()
main = do
    context <- configure "1.0" None (simpleConfig [])
    context' <- initializeTelemetry [consoleExporter, structuredExporter, honeycombExporter] context
    executeWith context' $ do
        info "Starting..."
        launchWebserver 8080 application

You can then describe your webservice Application, for example

application :: Application
application = request sendResponse =
    sendResponse (responseLBS status200 [] "Hello World")

performs the heroic duty of replying to you with the given string. In practice, if you're using something like servant to define the shape of your webservice its serve function will give you the Application you're trying to run.

Logging output is sent to the telemtry channel. If you run your program with the console exporter, and hit something like http://localhost:8080/hello?question=answer will see something like this:

$ hello-service --telemetry=console
03:16:01Z (00.002) Starting...
03:16:04Z (00.259)                                             <-- this is the request duration, 259 ms
/hello:                                                        <-- the base of the context path aka "endpoint"
  request.method = "GET"
  request.path = "/hello?question=answer"                      <-- the full context path with query string
  response.status_code = "200"

This is useful for debugging during development but for production you are recommended to use the structured logging output or to send the traces to an observability service; this will be the root span of a trace.

Documentation

type Port = Int

TCP port number.

launchWebserver :: Port -> Application -> Program τ ()

Given a WAI Application, run a Warp webserver on the specified port from within the Program monad.