extern/httpie-cli
1
0
Fork 1
mirror of https://github.com/httpie/cli.git synced 2025-03-13 06:18:33 +01:00
Code Issues Packages Projects Releases Wiki Activity

update docs for protocol negotiation and gen man

Browse Source
This commit is contained in:
Ahmed TAHRI 2024-06-26 16:09:58 +01:00
parent f989e5ecad
commit d02b88254d
4 changed files with 75 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/README.md
View File

@ -1890,6 +1890,41 @@ By opposition to the previous section, you can force the HTTP/3, HTTP/2 or HTTP/
$ https --http3 pie.dev/get
```
For HTTP (unencrypted) URLs, you can enforce HTTP 1 or HTTP 2 but not HTTP 3.
You cannot enforce multiple protocols like `--http2 --http3`, they (toggles) are mutually exclusive.
### Protocol selection
By default, HTTPie follows what modern browser do to choose a protocol.
#### For HTTP URLs
HTTP/1.1 will always be chosen unless you specified `--http2` to enforce HTTP/2 with prior knowledge (also known as h2c).
Notes:
- You cannot enforce HTTP/3.
- You cannot disable both HTTP/1.1 and HTTP/2.
#### For HTTPS URLs
When reaching to an SSL/TLS server, HTTPie negotiate the protocol through what is called the ALPN extension during
the handshake.
Basically, HTTPie says during the "Hello" phase: "I can speak HTTP/1.1 and HTTP/2 over TCP, and you?".
Depending on what the server respond to us, we will choose a mutual supported protocols.
Nowadays, it is most certainly be HTTP/2 by default.
Some specifics:
- You cannot disable all three protocols.
- Those toggles do not apply to the DNS-over-HTTPS custom resolver. You will have to specify it within the resolver URL.
- When reaching a HTTPS URL, the ALPN extension sent during SSL/TLS handshake is affected.
- HTTPie never tries HTTP/3 by default unless something hints us that it is possible.
##### HTTP 3 Negotiation
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).
@ -1897,30 +1932,7 @@ The remote server yield its support for HTTP/3 in the `Alt-Svc` header, if prese
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
Following `Force HTTP/3, HTTP/2 and HTTP/1` and `Disable HTTP/1, HTTP/2, or HTTP/3`, you may find a summary on how to make HTTPie negotiate a
specific protocol.
| Arguments | HTTP/1.1 <br>enabled | HTTP/2 <br>enabled | HTTP/3 <br>enabled |
|----------------------------------:|:--------------------:|:------------------:|:------------------:|
| (Default) | ✔ | ✔ | ✔ |
| `--disable-http1` | ✗ | ✔ | ✔ |
| `--disable-http2` | ✔ | ✗ | ✔ |
| `--disable-http3` | ✔ | ✔ | ✗ |
| `--disable-http2 --disable-http3` | ✔ | ✗ | ✗ |
| `--disable-http1 --disable-http2` | ✗ | ✗ | ✔ |
| `--http1` | ✔ | ✗ | ✗ |
| `--http2` | ✗ | ✔ | ✗ |
| `--http3` | ✗ | ✗ | ✔ |
Some specifics, through:
- You cannot enforce HTTP/3 over non HTTPS URLs.
- You cannot disable both HTTP/1.1 and HTTP/2 for non HTTPS URLs.
- Of course, you cannot disable all three protocols.
- Those toggles do not apply to the DNS-over-HTTPS custom resolver. You will have to specify it within the resolver URL.
- When reaching a HTTPS URL, the ALPN extension sent during SSL/TLS handshake is affected.
Note: HTTPie caches what server are QUIC compatible in the `config` directory so that we can remember.
## Custom DNS resolver

20
extras/man/http.1
View File

@ -1,5 +1,5 @@
.\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
.TH http 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
.TH http 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
.SH NAME
http
.SH SYNOPSIS
@ -496,12 +496,30 @@ Bypass dot segment (/../ or /./) URL squashing.
Enable streaming via chunked transfer encoding. The Transfer-Encoding header is set to chunked.
.IP "\fB\,--disable-http1\/\fR"
Disable the HTTP/1 protocol.
.IP "\fB\,--http1\/\fR"
Use the HTTP/1 protocol for the request.
.IP "\fB\,--disable-http2\/\fR"
Disable the HTTP/2 protocol.
.IP "\fB\,--http2\/\fR"
Use the HTTP/2 protocol for the request.
.IP "\fB\,--disable-http3\/\fR"

2
extras/man/httpie.1
View File

@ -1,5 +1,5 @@
.\" This file is auto-generated from the parser declaration in httpie/manager/cli.py by extras/scripts/generate_man_pages.py.
.TH httpie 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
.TH httpie 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
.SH NAME
httpie
.SH SYNOPSIS

20
extras/man/https.1
View File

@ -1,5 +1,5 @@
.\" This file is auto-generated from the parser declaration in httpie/cli/definition.py by extras/scripts/generate_man_pages.py.
.TH https 1 "2024-01-01" "HTTPie 4.0.0.b1" "HTTPie Manual"
.TH https 1 "2024-06-25" "HTTPie 4.0.0" "HTTPie Manual"
.SH NAME
https
.SH SYNOPSIS
@ -496,12 +496,30 @@ Bypass dot segment (/../ or /./) URL squashing.
Enable streaming via chunked transfer encoding. The Transfer-Encoding header is set to chunked.
.IP "\fB\,--disable-http1\/\fR"
Disable the HTTP/1 protocol.
.IP "\fB\,--http1\/\fR"
Use the HTTP/1 protocol for the request.
.IP "\fB\,--disable-http2\/\fR"
Disable the HTTP/2 protocol.
.IP "\fB\,--http2\/\fR"
Use the HTTP/2 protocol for the request.
.IP "\fB\,--disable-http3\/\fR"