warp-tls-simple 0.1.0.1 → 0.1.0.2

raw patch · 2 files changed

+124/−7 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• src/Network/Wai/Handler/WarpTLS/Simple.hs +123/−6
• warp-tls-simple.cabal +1/−1

@@ -2,15 +2,68 @@ {-# LANGUAGE StandaloneDeriving #-} {-# LANGUAGE TemplateHaskell #-} +{- |+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+@+-} module Network.Wai.Handler.WarpTLS.Simple (-  -- * Type+  -- * TLS Configuration   TLSConfig (..), -  -- * Function+  -- * Server Functions   tlsConfigResolve,   startWarpServer, -  -- * CLI parser+  -- * CLI Integration   tlsConfigParser, ) where @@ -32,7 +85,42 @@ opensslBin :: FilePath opensslBin = $(staticWhich "openssl") --- | TLS configuration with HTTPS enabled by default+{- | 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.+-} data TLSConfig   = -- | No TLS - run HTTP only (explicit)     TLSDisabled@@ -47,7 +135,16 @@     TLSAuto -> "TLSAuto"     TLSExplicit tlsSettings -> "TLSExplicit (user-provided certificates): " <> Text.Show.show (WarpTLS.getCertSettings tlsSettings) --- | Parser for TLS configuration with HTTPS enabled by default+{- | 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.+-} tlsConfigParser :: Parser TLSConfig tlsConfigParser =   noHttpsMode <|> tlsExplicitMode <|> defaultMode@@ -75,6 +172,17 @@     -- Default to auto-generation (HTTPS enabled by default)     defaultMode = pure TLSAuto +{- | Resolve TLS configuration to WarpTLS settings++Converts a 'TLSConfig' to the appropriate 'WarpTLS.TLSSettings' for the Warp server:++* 'TLSDisabled' → 'Nothing' (HTTP mode)+* 'TLSAuto' → Auto-generates certificates in @stateDir\/tls\/@+* 'TLSExplicit' → Uses provided settings++For 'TLSAuto', certificates are generated once and reused on subsequent runs.+The hostname "localhost" is used for certificate generation.+-} tlsConfigResolve :: FilePath -> TLSConfig -> IO (Maybe WarpTLS.TLSSettings) tlsConfigResolve stateDir = \case   TLSDisabled -> pure Nothing@@ -242,7 +350,16 @@ generateCertificates certDir hostArg =   generateCertificateWithRequest certDir (defaultCertRequest hostArg) --- | Start a Warp server with optional TLS+{- | 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.+-} startWarpServer :: Warp.Settings -> FilePath -> TLSConfig -> Application -> IO () startWarpServer settings stateDir tlsConfig app =   tlsConfigResolve stateDir tlsConfig >>= \case

@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           warp-tls-simple-version: 0.1.0.1+version: 0.1.0.2 synopsis:       Simple TLS configuration for Warp description:    Simplified TLS setup and certificate generation for Warp servers category:       Web