From 78aa25d51a0b74b8b99801158b309bac4651f36b Mon Sep 17 00:00:00 2001 From: Jakub Roztocil Date: Mon, 3 Jun 2024 13:49:36 +0200 Subject: [PATCH] Docs wip --- CHANGELOG.md | 18 ++++++++---------- docs/README.md | 45 ++++++++++++++++++++++++++------------------- 2 files changed, 34 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 64c3ccc68c..70009dd48f 100644 --- 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 index a979f1c0bd..d0e7b022cd 100644 --- 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
enabled | HTTP/2
enabled | HTTP/3
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.