libstore/filetransfer: support HTTP/3 transfers if the user requests it

This adds the enablement code to support HTTP/3 if the user requests it.

We leave it disabled because h3 is not onpar with h2 performance.

Change-Id: I1fd3d4c97b972dcf36bccacc6c9a8290e22b31e0
Signed-off-by: Raito Bezarius <raito@lix.systems>

doc/manual/rl-next/http3.md

@@ -0,0 +1,34 @@
+---
+synopsis: Lix supports HTTP/3 behind `--http3`
+issues: [fj#1033]
+category: "Features"
+credits: [raito, horrors]
+---
+
+Lix now supports HTTP/3 for file transfers when the linked curl version
+supports it.
+
+By default, HTTP/3 is disabled notably due to performance issues reported in
+mid-2024. [More details
+here](https://daniel.haxx.se/blog/2024/06/10/http-3-in-curl-mid-2024/).
+
+As of 2025-11-14, [NixOS official cache](https://cache.nixos.org) supports
+HTTP/3 via Fastly. [More info
+here](https://github.com/NixOS/infra/commit/157fa70e46afbd6338a32407be461fce05c57bf8).
+
+To enable HTTP/3:
+
+* Use `--http3` for individual transfers.
+* Add `http3 = true` in your Nix configuration for permanent activation.
+
+To disable it, use `--no-http3`.
+
+**Note**:
+
+* `--no-http2 --http3` will still enable both HTTP/2 and HTTP/3.
+* `--http2 --http3` will prioritize HTTP/3 and fall back to HTTP/2 (and then
+  HTTP/1.1).
+
+These are current CLI limitations. In the future, we plan to replace `--httpX`
+options with `--max-http-version [1,2,3]` for easier version selection in Lix
+transfers.

lix/libstore/file-transfer-settings/http3.md

@@ -0,0 +1,7 @@
+---
+name: http3
+internalName: enableHttp3
+type: bool
+default: false
+---
+Whether to enable HTTP/3 support.

lix/libstore/filetransfer.cc

@@ -197,7 +197,9 @@ struct TransferItem
                 .c_str()
         );
         curl_easy_setopt(req.get(), CURLOPT_PIPEWAIT, 1);
-        if (fileTransferSettings.enableHttp2) {
+        if (fileTransferSettings.enableHttp3) {
+            curl_easy_setopt(req.get(), CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_3);
+        } else if (fileTransferSettings.enableHttp2) {
             curl_easy_setopt(req.get(), CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_2TLS);
         } else {
             curl_easy_setopt(req.get(), CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);

lix/libstore/meson.build

@@ -55,6 +55,7 @@ file_transfer_setting_definitions = files(
   'file-transfer-settings/download-attempts.md',
   'file-transfer-settings/http-connections.md',
   'file-transfer-settings/http2.md',
+  'file-transfer-settings/http3.md',
   'file-transfer-settings/initial-connect-timeout.md',
   'file-transfer-settings/max-connect-timeout.md',
   'file-transfer-settings/stalled-download-timeout.md',