Documentation and packaging improvements for network-transport-quic

Author: LaurentRDC

packages/network-transport-quic/CHANGELOG.md

@@ -1,4 +1,8 @@
 
+2026-01-01  Laurent P. René de Cotret <laurent.decotret@outlook.com> 0.1.1
+
+* Documentation and packaging improvements.
+
 2026-01-01  Laurent P. René de Cotret <laurent.decotret@outlook.com> 0.1.0
 
 * Initial release.

packages/network-transport-quic/README.md

@@ -0,0 +1,39 @@
+# `network-transport-quic`
+
+This package provides an implementation of the `network-transport` interface, where networking is done via the QUIC protocol. The primary use-case for this package is as a Cloud Haskell backend.
+
+QUIC has many advantages over TCP, including:
+
+* No head-of-line blocking. Independent streams mean packet loss on one stream doesn't stall others;
+* Connection migration. Connections survive IP address changes, which is important when a device switches from e.g. WIFI to 5G;
+* Built-in encryption via TLS 1.3;
+
+In benchmarks, `network-transport-quic` performs better than `network-transport-tcp` in dense network topologies. For example, if every `EndPoint` in your network connects to every other `EndPoint`, you might benefit greatly from switching to `network-transport-quic`! 
+
+## Usage example
+
+Provided you have a TLS 1.3 certificate, you can create a `Transport` like so:
+
+```haskell
+import Data.List.NonEmpty qualified as NonEmpty
+import Network.Transport.QUIC (QUICTransportConfig(..), createTransport, credentialLoadX509)
+
+main = do
+    let certificate = "path/to/cert.crt"
+        key = "path/to/cert.key"
+
+    creds <- credentialLoadX509 certificate key
+    case creds of
+        Left error_message -> error error_message
+        Right credential -> do
+            let config = QUICTransportConfig
+                            { hostName = "my.hostname.com" -- or some IP address
+                            , serviceName = "https" -- alternatively, some port number
+                            , credentials = NonEmpty.singleton credential
+                            , validateCredentials = True -- should be 'False' for self-signed certificate
+                            }
+            transport <- createTransport config
+            ...
+```
+
+There are tools online to help create self-signed TLS 1.3 certificates.

packages/network-transport-quic/network-transport-quic.cabal

@@ -1,6 +1,6 @@
 cabal-version: 3.0
 Name:          network-transport-quic
-Version:       0.1.0
+Version:       0.1.1
 build-Type:    Simple
 License:       BSD-3-Clause
 License-file:  LICENSE
@@ -11,10 +11,20 @@ Stability:     experimental
 Homepage:      https://haskell-distributed.github.io
 Bug-Reports:   https://github.com/haskell-distributed/distributed-process/issues
 Synopsis:      Networking layer for Cloud Haskell based on QUIC
-Description:   Networking layer for Cloud Haskell based on QUIC
+Description:
+  Networking layer for Cloud Haskell based on QUIC.
+
+  The QUIC protocol has several advantages over TCP, including built-in encryption via TLS 1.3,
+  support for connection migration (e.g. when transitioning from WIFI to 5G), and stream multiplexing which
+  eliminates head-of-line blocking.
+
+  In dense network topologies, using ["Network.Transport.QUIC"] may improve performance by a factor of 2 over
+  other transport implementations.
 tested-with:   GHC==8.10.7 GHC==9.0.2 GHC==9.2.8 GHC==9.4.8 GHC==9.6.7 GHC==9.8.4 GHC==9.10.3 GHC==9.12.2
 Category:      Network
-extra-doc-files: CHANGELOG.md
+extra-doc-files:
+               README.md
+               CHANGELOG.md
 extra-source-files:
                test/credentials/cert.crt
                test/credentials/cert.key