Docs wip

httpie · Jun 3, 2024 · 78aa25d · 78aa25d
1 parent e3cbc7f
commit 78aa25d
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 29 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,33 +5,31 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [4.0.0.b1](https://github.com/httpie/cli/compare/3.2.2...master) (unreleased)
 
-- Switched from [`requests`](https://github.com/psf/requests) to the compatible [`niquests`](https://github.com/jawah/niquests). ([#1531](https://github.com/httpie/cli/pull/1531))
+- Switched from the [`requests`](https://github.com/psf/requests) library to the compatible [`niquests`](https://github.com/jawah/niquests). ([#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for HTTP/2, and HTTP/3 protocols. ([#523](https://github.com/httpie/cli/issues/523), [#692](https://github.com/httpie/cli/issues/692), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for IPv4/IPv6 enforcement with `-6` and `-4`. ([#94](https://github.com/httpie/cli/issues/94), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for alternative DNS resolvers via `--resolver`. DNS over HTTPS, DNS over TLS, DNS over QUIC, and DNS over UDP are accepted. ([#99](https://github.com/httpie/cli/issues/99), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for binding to a specific network adapter with `--interface`. ([#1422](https://github.com/httpie/cli/issues/1422), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for specifying the local port with `--local-port`. ([#1456](https://github.com/httpie/cli/issues/1456), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added the ability to [unset](https://httpie.io/docs/cli/default-request-headers) the `User-Agent`, and `Accept-Encoding` headers. ([#1502](https://github.com/httpie/cli/issues/1502))
-  The `Host` header cannot be unset due to support for HTTP/2+ (internally translated into `:authority`).
-- Added request metadata for the TLS certificate, negotiated version with cipher, the revocation status and the remote peer IP address. ([#1495](https://github.com/httpie/cli/issues/1495)) ([#1023](https://github.com/httpie/cli/issues/1023)) ([#826](https://github.com/httpie/cli/issues/826)) ([#1531](https://github.com/httpie/cli/pull/1531))
+- Added request metadata for the TLS certificate, negotiated version with cipher, the revocation status and the remote peer IP address. ([#1495](https://github.com/httpie/cli/issues/1495), [#1023](https://github.com/httpie/cli/issues/1023), [#826](https://github.com/httpie/cli/issues/826), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support to load the operating system trust store for the peer certificate validation. ([#480](https://github.com/httpie/cli/issues/480), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added support for using the system trust store to retrieve root CAs for verifying TLS certificates. ([#1531](https://github.com/httpie/cli/pull/1531))
 - Added detailed timings in response metadata with DNS resolution, established, TLS handshake, and request sending delays. ([#1023](https://github.com/httpie/cli/issues/1023), [#1531](https://github.com/httpie/cli/pull/1531))
 - Added automated resolution of hosts ending with `.localhost` to the default loopback address. ([#1458](https://github.com/httpie/cli/issues/1458), [#1527](https://github.com/httpie/cli/issues/1527))
-- Removed support for `pyopenssl`. ([#1531](https://github.com/httpie/cli/pull/1531))
-- Removed support for dead SSL protocols < TLS 1.0 (e.g. sslv3) as per pyopenssl removal. ([#1531](https://github.com/httpie/cli/pull/1531))
-- Removed dependency on `requests_toolbelt` in favor of directly including `MultipartEncoder` into HTTPie due to its direct dependency to requests. ([#1531](https://github.com/httpie/cli/pull/1531))
-- Removed dependency on `multidict` in favor of implementing an internal one due to often missing pre-built wheels. ([#1522](https://github.com/httpie/cli/issues/1522), [#1531](https://github.com/httpie/cli/pull/1531))
 - Fixed the case when multiple headers where concatenated in the response output. ([#1413](https://github.com/httpie/cli/issues/1413), [#1531](https://github.com/httpie/cli/pull/1531))
 - Fixed an edge case where HTTPie could be lead to believe data was passed in stdin, thus sending a POST by default. ([#1551](https://github.com/httpie/cli/issues/1551), [#1531](https://github.com/httpie/cli/pull/1531))
   This fix has the particularity to consider 0 byte long stdin buffer as absent stdin. Empty stdin buffer will be ignored.
-- Slightly improved performance while downloading by setting chunk size to `-1` to retrieve packets as they arrive. ([#1531](https://github.com/httpie/cli/pull/1531))
-- Removed support for keeping the original casing of HTTP headers. This come from an outer constraint by newer protocols, namely HTTP/2+ that normalize header keys by default.
-  From the HTTPie user perspective, they are "prettified" on the output by default. e.g. "x-hello-world" is displayed as "X-Hello-World".
+- Improved performance while downloading by setting chunk size to `-1` to retrieve packets as they arrive. ([#1531](https://github.com/httpie/cli/pull/1531))
 - Fixed multipart form data having filename not rfc2231 compliant when name contain non-ascii characters. ([#1401](https://github.com/httpie/cli/issues/1401))
 - Fixed issue where the configuration directory was not created at runtime that made the update fetcher run everytime. ([#1527](https://github.com/httpie/cli/issues/1527))
 - Fixed cookie persistence in HTTPie session when targeting localhost. They were dropped due to the standard library. ([#1527](https://github.com/httpie/cli/issues/1527))
 - Fixed downloader when trying to fetch compressed content. The process will no longer exit with the "Incomplete download" error. ([#1554](https://github.com/httpie/cli/issues/1554), [#423](https://github.com/httpie/cli/issues/423), [#1527](https://github.com/httpie/cli/issues/1527))
+- Removed support for preserving the original casing of HTTP headers. This comes as a constraint of newer protocols, namely HTTP/2+ that normalize header keys by default. From the HTTPie user perspective, they are "prettified" in the output by default. e.g. `x-hello-world` is displayed as `X-Hello-World`.
+- Removed support for `pyopenssl`. ([#1531](https://github.com/httpie/cli/pull/1531))
+- Removed support for dead SSL protocols < TLS 1.0 (e.g. sslv3) as per pyopenssl removal. ([#1531](https://github.com/httpie/cli/pull/1531))
+- Removed dependency on `requests_toolbelt` in favor of directly including `MultipartEncoder` into HTTPie due to its direct dependency to requests. ([#1531](https://github.com/httpie/cli/pull/1531))
+- Removed dependency on `multidict` in favor aof an internal one due to often missing pre-built wheels. ([#1522](https://github.com/httpie/cli/issues/1522), [#1531](https://github.com/httpie/cli/pull/1531))
 
 Existing plugins are expected to work without any changes. The only caveat would be that certain plugin explicitly require `requests`.
 Future contributions may be made in order to relax the constraints where applicable.

diff --git a/docs/README.md b/docs/README.md
@@ -286,7 +286,7 @@ Note that on your machine, the version name will have the `.dev0` suffix.
 ### HTTP/3 support
 
 Support for HTTP/3 is available by default if both your interpreter and architecture are served by `qh3` published pre-built wheels.
-The underlying library **Niquests** does not enforce its installation in order to avoid friction for most users.
+The underlying library Niquests does not enforce its installation in order to avoid friction for most users.
 
 See https://urllib3future.readthedocs.io/en/latest/user-guide.html#http-2-and-http-3-support to learn more.
 
@@ -1193,22 +1193,24 @@ You can read headers from a file by using the `:@` operator. This would also eff
 $ http pie.dev/headers X-Data:@files/text.txt
 ```
 
-### Empty headers and header un-setting
+### Empty request headers
 
-To unset a previously specified header (such a one of the default headers), use `Header:`:
+To send a header with an empty value, use `Header;`, with a semicolon:
 
 ```bash
-$ http pie.dev/headers Accept: User-Agent:
+$ http pie.dev/headers 'Header;'
 ```
 
-To send a header with an empty value, use `Header;`, with a semicolon:
+### Header un-setting
+
+To unset a previously specified header or one of the [default headers](#default-request-headers), use the `Header:` notation:
 
 ```bash
-$ http pie.dev/headers 'Header;'
+$ http pie.dev/headers Accept: User-Agent:
 ```
 
-Please note that some internal headers, such as `Content-Length`, can’t be unset if
-they are automatically added by the client itself.
+Please note that some internal headers, such as `Content-Length`, can’t be unset if  they are automatically added by the client itself.
+Also, the `Host` header cannot be unset due to support for HTTP/2+ (internally translated into `:authority`)
 
 ### Multiple header values with the same name
 
@@ -1864,7 +1866,11 @@ $ http --chunked pie.dev/post @files/data.xml
 $ cat files/data.xml | http --chunked pie.dev/post
 ```
 
-## Disable HTTP/2, or HTTP/3
+## Supported HTTP versions
+
+HTTPie has full support for HTTP/1.1, HTTP/2, and HTTP/3.
+
+### Disable HTTP/2, or HTTP/3
 
 You can at your own discretion toggle on and off HTTP/2, or/and HTTP/3.
 
@@ -1876,7 +1882,7 @@ $ https --disable-http2 PUT pie.dev/put hello=world
 $ https --disable-http3 PUT pie.dev/put hello=world
 ```
 
-## Force HTTP/3
+### Force HTTP/3
 
 By opposition to the previous section, you can force the HTTP/3 negotiation.
 
@@ -1887,21 +1893,22 @@ $ https --http3 pie.dev/get
 By default, HTTPie cannot negotiate HTTP/3 without a first HTTP/1.1, or HTTP/2 successful response unless the
 remote host specified a DNS HTTPS record that indicate its support (and by using a custom DNS resolver, see bellow section).
 
-The remote server yield its support for HTTP/3 in the Alt-Svc header, if present HTTPie will issue
+The remote server yield its support for HTTP/3 in the `Alt-Svc` header, if present HTTPie will issue
 the successive requests via HTTP/3. You may use that argument in case the remote peer does not support
 either HTTP/1.1 or HTTP/2.
 
-## Protocol combinations
+### Protocol combinations
 
 Following `Force HTTP/3` and `Disable HTTP/2, or HTTP/3`, you may find a summary on how to make HTTPie negotiate a
 specific protocol.
 
-| Argument(s)                       | Enabled protocol(s) |
-|-----------------------------------|---------------------|
-| `--disable-http2`                 | HTTP/1.1 or HTTP/3  |
-| `--disable-http2 --disable-http3` | HTTP/1.1            |
-| `--disable-http3`                 | HTTP/1.1 or HTTP/2  |
-| `--http3`                         | HTTP/3              |
+|                         Arguments | HTTP/1.1 <br>enabled | HTTP/2 <br>enabled | HTTP/3 <br>enabled |
+|----------------------------------:|:--------------------:|:------------------:|:------------------:|
+|                         (Default) |          ✔           |         ✔          |         ✔          |
+|                 `--disable-http2` |          ✔           |         ✗          |         ✔          |
+|                 `--disable-http3` |          ✔           |         ✔          |         ✗          |
+| `--disable-http2 --disable-http3` |          ✔           |         ✗          |         ✗          |
+|                         `--http3` |          ✗           |         ✗          |         ✔          |
 
 You cannot enforce HTTP/2 without prior knowledge nor can you negotiate it without TLS and ALPN.
 Also, you may not disable HTTP/1.1 as it is ultimately used as a fallback in case HTTP/2 and HTTP/3 are not supported.
@@ -1942,7 +1949,7 @@ You can specify multiple entries, concatenated with a comma:
 $ https --resolver "pie.dev:10.10.4.1,re.pie.dev:10.10.8.1" pie.dev/get
 ```
 
-## Attach to a specific network adapter
+## Network interface
 
 In order to bind emitted request from a specific network adapter you can use the `--interface` flag.