warp-tls-simple
Safe HaskellNone
LanguageGHC2021

Network.Wai.Handler.WarpTLS.Simple

Description

Simplified TLS configuration for Warp servers with automatic certificate generation

This module provides a simplified interface for running Warp servers with TLS support, including automatic self-signed certificate generation for development environments.

The main design goals are:

  • HTTPS by default: TLS is enabled by default with automatic certificate generation
  • Zero-configuration development: Works out of the box for local development
  • Production-ready: Supports custom certificates for production deployment
  • CLI integration: Provides tlsConfigParser for command-line argument parsing

Quick Start

import Network.Wai.Handler.WarpTLS.Simple
import Network.Wai.Handler.Warp qualified as Warp

main :: IO ()
main = do
  let settings = Warp.defaultSettings & Warp.setPort 8080
  startWarpServer settings "./state" TLSAuto myWaiApplication

Certificate Management

The module supports three TLS configurations:

  • TLSAuto - Automatically generates self-signed certificates (default)
  • TLSExplicit - Uses user-provided certificate and key files
  • TLSDisabled - Runs HTTP only (must be explicitly requested)

Auto-generated certificates include Subject Alternative Names (SAN) for:

  • localhost and the specified hostname
  • Common local network IP ranges (127.0.0.1, 192.168.*.*, 10.*.*.*, etc.)
  • IPv6 loopback (::1)

CLI Integration

data MyAppConfig = MyAppConfig
  { port :: Int
  , tlsConfig :: TLSConfig
  }

myConfigParser :: Parser MyAppConfig
myConfigParser = MyAppConfig
  <$> option auto (long "port" <> value 8080)
  <*> tlsConfigParser
Synopsis

TLS Configuration

data TLSConfig Source #

TLS configuration with HTTPS enabled by default

This type represents the three supported TLS modes for the Warp server:

TLSDisabled
HTTP-only mode. Must be explicitly requested with --no-https flag. This is useful for development behind a reverse proxy or when TLS termination happens elsewhere.
TLSAuto
Default mode. Automatically generates self-signed certificates for HTTPS. Certificates are stored in <stateDir>/tls/ and include SAN entries for local development. This provides zero-configuration HTTPS for development environments.
TLSExplicit
Production mode with user-provided certificates. Requires both certificate and private key files specified via --tls-cert and --tls-key flags.

Examples

Auto-generated certificates (default): tlsConfig = TLSAuto

Custom certificates for production: tlsSettings <- WarpTLS.tlsSettings "/path/to/cert.pem" "/path/to/key.pem" tlsConfig = TLSExplicit tlsSettings

HTTP-only mode: tlsConfig = TLSDisabled

The Show instance provides debugging information including certificate details for TLSExplicit configurations.

Constructors

TLSDisabled

No TLS - run HTTP only (explicit)

TLSAuto

TLS with auto-generated certificates (default)

TLSExplicit TLSSettings

TLS with user-provided certificate and key files

Instances

Instances details
Show TLSConfig Source # 
Instance details

Defined in Network.Wai.Handler.WarpTLS.Simple

Methods

showsPrec :: Int -> TLSConfig -> ShowS #

show :: TLSConfig -> String #

showList :: [TLSConfig] -> ShowS #

Server Functions

tlsConfigResolve :: FilePath -> TLSConfig -> IO (Maybe TLSSettings) Source #

Resolve TLS configuration to WarpTLS settings

Converts a TLSConfig to the appropriate TLSSettings for the Warp server:

For TLSAuto, certificates are generated once and reused on subsequent runs. The hostname "localhost" is used for certificate generation.

startWarpServer :: Settings -> FilePath -> TLSConfig -> Application -> IO () Source #

Start a Warp server with TLS support

High-level function that combines Warp settings, TLS configuration, and application:

  • Resolves the TLS configuration using the state directory
  • Starts HTTP server if TLS is disabled
  • Starts HTTPS server if TLS is enabled

This is the main entry point for applications using this module.

CLI Integration

tlsConfigParser :: Parser TLSConfig Source #

Command-line parser for TLS configuration

Provides optparse-applicative integration with HTTPS enabled by default:

  • --no-https - Disable HTTPS
  • --tls-cert FILE --tls-key FILE - Use custom certificates
  • Default - Auto-generate certificates

Both certificate options must be provided together.