Mercurial > hgrepos > Python2 > PyMuPDF

comparison mupdf-source/thirdparty/curl/docs/HTTP2.md @ 2:b50eed0cc0ef upstream

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
ADD: MuPDF v1.26.7: the MuPDF source as downloaded by a default build of PyMuPDF 1.26.4. The directory name has changed: no version number in the expanded directory now.
author Franz Glasner <fzglas.hg@dom66.de>
date Mon, 15 Sep 2025 11:43:07 +0200
parents
children
comparison
equal deleted inserted replaced
1:1d09e1dec1d9 2:b50eed0cc0ef
1 HTTP/2 with curl
2 ================
3
4 [HTTP/2 Spec](https://www.rfc-editor.org/rfc/rfc7540.txt)
5 [http2 explained](https://daniel.haxx.se/http2/)
6
7 Build prerequisites
8 -------------------
9 - nghttp2
10 - OpenSSL, libressl, BoringSSL, NSS, GnutTLS, mbedTLS, wolfSSL or Schannel
11 with a new enough version.
12
13 [nghttp2](https://nghttp2.org/)
14 -------------------------------
15
16 libcurl uses this 3rd party library for the low level protocol handling
17 parts. The reason for this is that HTTP/2 is much more complex at that layer
18 than HTTP/1.1 (which we implement on our own) and that nghttp2 is an already
19 existing and well functional library.
20
21 We require at least version 1.0.0.
22
23 Over an http:// URL
24 -------------------
25
26 If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will
27 include an upgrade header in the initial request to the host to allow
28 upgrading to HTTP/2.
29
30 Possibly we can later introduce an option that will cause libcurl to fail if
31 not possible to upgrade. Possibly we introduce an option that makes libcurl
32 use HTTP/2 at once over http://
33
34 Over an https:// URL
35 --------------------
36
37 If `CURLOPT_HTTP_VERSION` is set to `CURL_HTTP_VERSION_2_0`, libcurl will use
38 ALPN (or NPN) to negotiate which protocol to continue with. Possibly introduce
39 an option that will cause libcurl to fail if not possible to use HTTP/2.
40
41 `CURL_HTTP_VERSION_2TLS` was added in 7.47.0 as a way to ask libcurl to prefer
42 HTTP/2 for HTTPS but stick to 1.1 by default for plain old HTTP connections.
43
44 ALPN is the TLS extension that HTTP/2 is expected to use. The NPN extension is
45 for a similar purpose, was made prior to ALPN and is used for SPDY so early
46 HTTP/2 servers are implemented using NPN before ALPN support is widespread.
47
48 `CURLOPT_SSL_ENABLE_ALPN` and `CURLOPT_SSL_ENABLE_NPN` are offered to allow
49 applications to explicitly disable ALPN or NPN.
50
51 SSL libs
52 --------
53
54 The challenge is the ALPN and NPN support and all our different SSL
55 backends. You may need a fairly updated SSL library version for it to provide
56 the necessary TLS features. Right now we support:
57
58 - OpenSSL: ALPN and NPN
59 - libressl: ALPN and NPN
60 - BoringSSL: ALPN and NPN
61 - NSS: ALPN and NPN
62 - GnuTLS: ALPN
63 - mbedTLS: ALPN
64 - Schannel: ALPN
65 - wolfSSL: ALPN
66 - Secure Transport: ALPN
67
68 Multiplexing
69 ------------
70
71 Starting in 7.43.0, libcurl fully supports HTTP/2 multiplexing, which is the
72 term for doing multiple independent transfers over the same physical TCP
73 connection.
74
75 To take advantage of multiplexing, you need to use the multi interface and set
76 `CURLMOPT_PIPELINING` to `CURLPIPE_MULTIPLEX`. With that bit set, libcurl will
77 attempt to re-use existing HTTP/2 connections and just add a new stream over
78 that when doing subsequent parallel requests.
79
80 While libcurl sets up a connection to a HTTP server there is a period during
81 which it doesn't know if it can pipeline or do multiplexing and if you add new
82 transfers in that period, libcurl will default to start new connections for
83 those transfers. With the new option `CURLOPT_PIPEWAIT` (added in 7.43.0), you
84 can ask that a transfer should rather wait and see in case there's a
85 connection for the same host in progress that might end up being possible to
86 multiplex on. It favours keeping the number of connections low to the cost of
87 slightly longer time to first byte transferred.
88
89 Applications
90 ------------
91
92 We hide HTTP/2's binary nature and convert received HTTP/2 traffic to headers
93 in HTTP 1.1 style. This allows applications to work unmodified.
94
95 curl tool
96 ---------
97
98 curl offers the `--http2` command line option to enable use of HTTP/2.
99
100 curl offers the `--http2-prior-knowledge` command line option to enable use of
101 HTTP/2 without HTTP/1.1 Upgrade.
102
103 Since 7.47.0, the curl tool enables HTTP/2 by default for HTTPS connections.
104
105 curl tool limitations
106 ---------------------
107
108 The command line tool won't do any HTTP/2 multiplexing even though libcurl
109 supports it, simply because the curl tool is not written to take advantage of
110 the libcurl API that's necessary for this (the multi interface). We have an
111 outstanding TODO item for this and **you** can help us make it happen.
112
113 The command line tool also doesn't support HTTP/2 server push for the same
114 reason it doesn't do multiplexing: it needs to use the multi interface for
115 that so that multiplexing is supported.
116
117 HTTP Alternative Services
118 -------------------------
119
120 Alt-Svc is an extension with a corresponding frame (ALTSVC) in HTTP/2 that
121 tells the client about an alternative "route" to the same content for the same
122 origin server that you get the response from. A browser or long-living client
123 can use that hint to create a new connection asynchronously. For libcurl, we
124 may introduce a way to bring such clues to the application and/or let a
125 subsequent request use the alternate route automatically.
126
127 [Detailed in RFC 7838](https://tools.ietf.org/html/rfc7838)